> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Summary API

> Retrieve a windowed, bucketed usage and spend summary for your Plivo account across messaging, voice, SIP Trunking, and transcription.

The `UsageSummary` object returns aggregated usage and spend for your account over a date window, bucketed by the granularity you choose and optionally filtered by subaccount, product, country, direction, error code, or hangup cause. Telecom traffic (messaging, voice, SIP Trunking, transcription) is returned in `usage`, and non-telecom billing rows (number charges, lookups, fees, taxes, adjustments) are returned in `other_charges`. Detail rows are paginated with an opaque cursor.

**API Endpoint**

```
https://api.plivo.com/v1/Account/{auth_id}/UsageSummary/
```

<Note>
  Authentication uses HTTP Basic Auth with your `AUTH ID` and `AUTH TOKEN`, the same as all Plivo Messaging APIs. The `auth_id` is taken from the URL path; any `auth_id` passed as a query parameter is silently ignored.
</Note>

<Note>
  At general availability this endpoint is available over the REST API only. Server SDK wrappers will be added in a future release.
</Note>

***

## Retrieve Usage Summary

Retrieves a paginated usage summary for the requested window.

```
GET https://api.plivo.com/v1/Account/{auth_id}/UsageSummary/
```

### Arguments

Only the parameters below are forwarded upstream. Any unknown query keys are silently dropped.

<ParamField body="subaccount_auth" type="string">
  Scope the summary to a single subaccount. Must be non-empty if provided. Omit to summarize the parent account and all subaccounts.
</ParamField>

<ParamField body="granularity" type="string" default="day">
  Bucket size for `usage` rows. One of `hour`, `day`, `month`, or `year`.
</ParamField>

<ParamField body="from_date" type="string" default="now − 7 days">
  Start of the reporting window in `YYYY-MM-DD` format. Inclusive.
</ParamField>

<ParamField body="to_date" type="string" default="today">
  End of the reporting window in `YYYY-MM-DD` format. **Exclusive** — rows with timestamps at or after `to_date` are not returned.
</ParamField>

<ParamField body="product" type="string" default="all">
  Restrict `usage` rows to one or more products. Repeatable, or pass as a comma-separated list. Valid values: `message`, `voice`, `zentrunk`, `transcription`, `other`.
</ParamField>

<ParamField body="error_code" type="string">
  Filter messaging rows by rolled-up DLR error code. Ignored for non-messaging products. See [Error Codes](/messaging/troubleshooting/error-codes) for the full list.
</ParamField>

<ParamField body="hangup_cause" type="string">
  Filter voice and SIP Trunking rows by hangup cause. Ignored for other products. See [Hangup Causes](/voice/troubleshooting/hangup-causes) for the full list.
</ParamField>

<ParamField body="direction" type="string">
  Filter rows by direction. One of `inbound` or `outbound`.
</ParamField>

<ParamField body="country" type="string">
  Filter rows by ISO-3166-1 alpha-2 country code (for example, `US`, `GB`, `IN`).
</ParamField>

<ParamField body="page_size" type="integer" default="100">
  Number of `usage` rows per page. Range: `1`–`1000`.
</ParamField>

<ParamField body="page_token" type="string">
  Opaque cursor returned as `next_page_token` on the previous response. Pass it back to fetch the next page.
</ParamField>

<Note>
  Unlike most Plivo list endpoints, `UsageSummary` uses cursor-based pagination (`page_token` / `next_page_token`) rather than the `limit` / `offset` model described in the [API Overview](/account/api/overview). See [Pagination](#pagination) below.
</Note>

### Window limits per granularity

The reporting window (`to_date` − `from_date`) is capped based on the `granularity` you request:

| Granularity | Maximum window                        |
| ----------- | ------------------------------------- |
| `hour`      | 7 days                                |
| `day`       | 92 days                               |
| `month`     | 24 months                             |
| `year`      | Unlimited (bounded by data retention) |

Exceeding the cap returns a `400` response that suggests the next-coarser granularity.

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.plivo.com/v1/Account/{auth_id}/UsageSummary/ \
      -u '<auth_id>:<auth_token>' \
      --data-urlencode "granularity=month" \
      --data-urlencode "from_date=2026-05-01" \
      --data-urlencode "to_date=2026-06-10" \
      --data-urlencode "page_size=100"
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "api_id": "c85662b6-0f35-4ea9-b8c3-22fa1e35a4c5",
  "meta": {
    "auth_id": "MAsampleaccountxxxx",
    "granularity": "month",
    "from_date": "2026-05-01T00:00:00Z",
    "to_date": "2026-06-10T00:00:00Z",
    "currency": "USD",
    "page_size": 100,
    "total_spent": 640.6663,
    "subaccount_spend": {
      "SAsamplesubacct0001": 0.192,
      "SAsamplesubacct0002": 19.7532
    }
  },
  "usage": [
    {
      "from_date": "2026-05-01T00:00:00Z",
      "to_date": "2026-06-01T00:00:00Z",
      "product": "message",
      "type": "sms",
      "country": "US",
      "direction": "outbound",
      "total_units": 1058,
      "total_amount": 5.6074,
      "surcharge": 3.703
    },
    {
      "from_date": "2026-05-01T00:00:00Z",
      "to_date": "2026-06-01T00:00:00Z",
      "product": "message",
      "type": "sms",
      "country": "PR",
      "direction": "outbound",
      "total_units": 5,
      "total_amount": 0.17145,
      "error_code": "200",
      "error_reason": "Opt-out block"
    },
    {
      "from_date": "2026-05-01T00:00:00Z",
      "to_date": "2026-06-01T00:00:00Z",
      "product": "message",
      "type": "sms",
      "subaccount_auth": "SAsamplesubacct0001",
      "country": "US",
      "direction": "outbound",
      "total_units": 1055,
      "total_amount": 6.6465,
      "surcharge": 4.7475
    },
    {
      "from_date": "2026-05-01T00:00:00Z",
      "to_date": "2026-06-01T00:00:00Z",
      "product": "voice",
      "type": "pstn",
      "country": "US",
      "direction": "outbound",
      "total_units": 52503,
      "duration_seconds": 52241,
      "total_amount": 0
    }
  ],
  "other_charges": [
    {
      "from_date": "2026-05-01T00:00:00Z",
      "to_date": "2026-06-01T00:00:00Z",
      "description": "Number Charges",
      "total_units": 129,
      "total_amount": 102.1245
    },
    {
      "from_date": "2026-06-01T00:00:00Z",
      "to_date": "2026-07-01T00:00:00Z",
      "description": "CNAM Lookup",
      "total_units": 48,
      "total_amount": 0.192
    }
  ]
}
```

***

## The Usage Summary Object

A successful response has three top-level fields: `api_id`, `meta`, and the two row arrays `usage` and `other_charges`.

<ParamField body="api_id" type="string">
  Unique identifier for the request.
</ParamField>

<ParamField body="meta" type="object">
  Summary metadata, window totals, and pagination cursor. See [meta](#meta) below.
</ParamField>

<ParamField body="usage" type="array">
  Paginated telecom-traffic rows for `message`, `voice`, `zentrunk`, and `transcription`. See [usage item](#usage-item) below. All `usage` filters (`product`, `country`, `direction`, `error_code`, `hangup_cause`, `subaccount_auth`) apply to this array.
</ParamField>

<ParamField body="other_charges" type="array">
  Non-telecom billing rows — number charges, lookups, fees, taxes, adjustments. See [other charges item](#other-charges-item) below.
</ParamField>

<Warning>
  **`other_charges` is page-1-only.** It is also omitted entirely when `subaccount_auth` is set or when the `product` filter excludes `other`. The reporting window applies to both arrays, but all other filters apply only to `usage`.
</Warning>

### meta

<ParamField body="auth_id" type="string">
  Account auth ID the summary belongs to.
</ParamField>

<ParamField body="subaccount_auth" type="string">
  Present only when the request was scoped to a subaccount via `subaccount_auth`.
</ParamField>

<ParamField body="granularity" type="string">
  Granularity used for bucketing `usage` rows.
</ParamField>

<ParamField body="from_date" type="string">
  Reporting window start (ISO-8601 timestamp).
</ParamField>

<ParamField body="to_date" type="string">
  Reporting window end (ISO-8601 timestamp). Exclusive.
</ParamField>

<ParamField body="currency" type="string">
  Currency of all monetary amounts in the response.
</ParamField>

<ParamField body="page_size" type="integer">
  Number of `usage` rows per page.
</ParamField>

<ParamField body="next_page_token" type="string">
  Opaque cursor for the next page. Omitted on the last page.
</ParamField>

<ParamField body="total_spent" type="float">
  Grand total (`usage` + `other_charges`) over the entire reporting window. **Returned on page 1 only.**
</ParamField>

<ParamField body="total_subaccount_spent" type="float">
  Window usage total for the scoped subaccount. Present only when the request was filtered by `subaccount_auth`. **Returned on page 1 only.**
</ParamField>

<ParamField body="subaccount_spend" type="object">
  Per-subaccount usage spend breakdown, keyed by subaccount auth ID. **Returned on page 1 only, and only when the request was not filtered by `subaccount_auth`.** Parent-level rows and `other_charges` are excluded from this map.
</ParamField>

### usage item

<ParamField body="from_date" type="string">
  Bucket start (ISO-8601 timestamp). Inclusive.
</ParamField>

<ParamField body="to_date" type="string">
  Bucket end (ISO-8601 timestamp). Exclusive.
</ParamField>

<ParamField body="product" type="string">
  One of `message`, `voice`, `zentrunk`, or `transcription`.
</ParamField>

<ParamField body="type" type="string">
  Product sub-type. For example, `sms` or `mms` for `message`, or `pstn` for `voice`.
</ParamField>

<ParamField body="subaccount_auth" type="string">
  Present for subaccount-scoped rows; omitted for parent-level rows.
</ParamField>

<ParamField body="country" type="string">
  ISO-3166-1 alpha-2 country code. Omitted for products that don't carry a country dimension.
</ParamField>

<ParamField body="direction" type="string">
  `inbound` or `outbound`. Omitted for products that don't carry a direction dimension.
</ParamField>

<ParamField body="total_units" type="integer">
  Units for this bucket. The unit depends on the product — see [Per-product unit meaning](#per-product-unit-meaning) below.
</ParamField>

<ParamField body="duration_seconds" type="float">
  Billed duration in seconds, for `voice`, `zentrunk`, and `transcription` rows. Omitted for other products.
</ParamField>

<ParamField body="total_amount" type="float">
  Total charge for the bucket.
</ParamField>

<ParamField body="surcharge" type="float">
  Surcharge component of `total_amount`, when applicable.
</ParamField>

<ParamField body="error_code" type="string">
  Rolled-up DLR error code on messaging rows. Empty on successful delivery. See [Error Codes](/messaging/troubleshooting/error-codes).
</ParamField>

<ParamField body="hangup_cause" type="string">
  Rolled-up hangup cause on voice and SIP Trunking rows. See [Hangup Causes](/voice/troubleshooting/hangup-causes).
</ParamField>

<ParamField body="error_reason" type="string">
  Human-readable label for whichever of `error_code` or `hangup_cause` is set on the row.
</ParamField>

#### Per-product unit meaning

| Product         | `total_units` means | `duration_seconds` means |
| --------------- | ------------------- | ------------------------ |
| `message`       | Message segments    | Not returned             |
| `voice`         | Call count          | Billed call duration     |
| `zentrunk`      | Call count          | Billed call duration     |
| `transcription` | Transcription count | Recording duration       |

### other charges item

<ParamField body="from_date" type="string">
  Charge window start (ISO-8601 timestamp).
</ParamField>

<ParamField body="to_date" type="string">
  Charge window end (ISO-8601 timestamp).
</ParamField>

<ParamField body="description" type="string">
  Customer-facing label for the charge. Examples: `Number Charges`, `CNAM Lookup`, `Other Charges`.
</ParamField>

<ParamField body="total_units" type="integer">
  Number of units billed.
</ParamField>

<ParamField body="total_amount" type="float">
  Total amount charged. Always positive.
</ParamField>

***

## Pagination

`usage` rows are paginated with an opaque cursor. When `meta.next_page_token` is present, pass it back as the `page_token` query parameter — keeping all other filters unchanged — to fetch the next page. The last page omits `next_page_token`.

<Warning>
  `total_spent`, `total_subaccount_spent`, `subaccount_spend`, and the entire `other_charges` array are returned **only on page 1** of a traversal. If you paginate, accumulate them from the first response — they will not appear on subsequent pages.
</Warning>

### Example: fetching page 2

```bash cURL theme={null}
curl -G https://api.plivo.com/v1/Account/{auth_id}/UsageSummary/ \
    -u '<auth_id>:<auth_token>' \
    --data-urlencode "granularity=month" \
    --data-urlencode "from_date=2026-05-01" \
    --data-urlencode "to_date=2026-06-10" \
    --data-urlencode "page_size=100" \
    --data-urlencode "page_token=<next_page_token-from-page-1>"
```

***

## Rate limits

This endpoint allows up to 20 requests per 60 seconds per account. Exceeding this limit returns a `429` response; retry after a short backoff.

***

## Response codes

| Code  | Meaning                                                                                                                                                            |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200` | Success. Returns a usage summary body.                                                                                                                             |
| `400` | Bad request. The upstream error message is surfaced verbatim so the caller can self-correct (for example, exceeding the window cap for the requested granularity). |
| `401` | Unauthorized. Invalid `AUTH ID` or `AUTH TOKEN`.                                                                                                                   |
| `403` | Forbidden. The request originated from a non-whitelisted IP. See [IP Whitelisting](/account/concepts/ip-whitelisting).                                             |
| `429` | Rate limit exceeded. See [Rate limits](#rate-limits).                                                                                                              |
| `502` | Upstream messaging-dashboard failure. Internal details are not leaked.                                                                                             |

### Example: window cap exceeded

```json theme={null}
{
  "api_id": "c85662b6-0f35-4ea9-b8c3-22fa1e35a4c5",
  "error": "granularity=day supports a max window of 92 days (requested 120 days); use granularity=month for larger windows"
}
```

***

## Notes

* `auth_id` is always taken from the URL path. A client cannot read another account's usage by passing a different `auth_id` in the query string.
* Upstream 4xx errors propagate their status code and message verbatim. Upstream 5xx or network failures are normalized to `502` with a generic message.