> ## 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]
>
> At general availability this endpoint is available over the REST API only. Server SDK wrappers will be added in a future release.

***

## 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.

**subaccount\_auth** `string`

Scope the summary to a single subaccount. Must be non-empty if provided. Omit to summarize the parent account and all subaccounts.

**granularity** `string` (default: day)

Bucket size for `usage` rows. One of `hour`, `day`, `month`, or `year`.

**from\_date** `string` (default: now − 7 days)

Start of the reporting window in `YYYY-MM-DD` format. Inclusive.

**to\_date** `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.

**product** `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`.

**error\_code** `string`

Filter messaging rows by rolled-up DLR error code. Ignored for non-messaging products. See [Error Codes](https://plivo.com/docs/messaging/troubleshooting/error-codes.md) for the full list.

**hangup\_cause** `string`

Filter voice and SIP Trunking rows by hangup cause. Ignored for other products. See [Hangup Causes](https://plivo.com/docs/voice/troubleshooting/hangup-causes.md) for the full list.

**direction** `string`

Filter rows by direction. One of `inbound` or `outbound`.

**country** `string`

Filter rows by ISO-3166-1 alpha-2 country code (for example, `US`, `GB`, `IN`).

**page\_size** `integer` (default: 100)

Number of `usage` rows per page. Range: `1`–`1000`.

**page\_token** `string`

Opaque cursor returned as `next_page_token` on the previous response. Pass it back to fetch the next page.

> [!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](https://plivo.com/docs/account/api/overview.md). See [Pagination](#pagination) below.

### 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

```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"
```

### Response

**api\_id** `string`

Unique identifier for the request.

**meta** `object`

Summary metadata, window totals, and pagination cursor. See [meta](#meta) below.

**usage** `array`

Paginated telecom-traffic rows for `message`, `voice`, `zentrunk`, and `transcription`. See [usage item](#usage-item) below.

**other\_charges** `array`

Non-telecom billing rows — number charges, lookups, fees, taxes, adjustments. See [other charges item](#other-charges-item) below.

```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_spend": 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`.

**api\_id** `string`

Unique identifier for the request.

**meta** `object`

Summary metadata, window totals, and pagination cursor. See [meta](#meta) below.

**usage** `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.

**other\_charges** `array`

Non-telecom billing rows — number charges, lookups, fees, taxes, adjustments. See [other charges item](#other-charges-item) below.

> [!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`.

### meta

**auth\_id** `string`

Account auth ID the summary belongs to.

**subaccount\_auth** `string`

Present only when the request was scoped to a subaccount via `subaccount_auth`.

**granularity** `string`

Granularity used for bucketing `usage` rows.

**from\_date** `string`

Reporting window start (ISO-8601 timestamp).

**to\_date** `string`

Reporting window end (ISO-8601 timestamp). Exclusive.

**currency** `string`

Currency of all monetary amounts in the response.

**page\_size** `integer`

Number of `usage` rows per page.

**next\_page\_token** `string`

Opaque cursor for the next page. Omitted on the last page.

**total\_spend** `float`

Grand total (`usage` + `other_charges`) over the entire reporting window. **Returned on page 1 only.**

**total\_subaccount\_spend** `float`

Window usage total for the scoped subaccount. Present only when the request was filtered by `subaccount_auth`. **Returned on page 1 only.**

**subaccount\_spend** `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.

### usage item

**from\_date** `string`

Bucket start (ISO-8601 timestamp). Inclusive.

**to\_date** `string`

Bucket end (ISO-8601 timestamp). Exclusive.

**product** `string`

One of `message`, `voice`, `zentrunk`, or `transcription`.

**type** `string`

Product sub-type. For example, `sms` or `mms` for `message`, or `pstn` for `voice`.

**subaccount\_auth** `string`

Present for subaccount-scoped rows; omitted for parent-level rows.

**country** `string`

ISO-3166-1 alpha-2 country code. Omitted for products that don't carry a country dimension.

**direction** `string`

`inbound` or `outbound`. Omitted for products that don't carry a direction dimension.

**total\_units** `integer`

Units for this bucket. The unit depends on the product — see [Per-product unit meaning](#per-product-unit-meaning) below.

**duration\_seconds** `float`

Billed duration in seconds, for `voice`, `zentrunk`, and `transcription` rows. Omitted for other products.

**total\_amount** `float`

Total charge for the bucket.

**surcharge** `float`

Surcharge component of `total_amount`, when applicable.

**error\_code** `string`

Rolled-up DLR error code on messaging rows. Empty on successful delivery. See [Error Codes](https://plivo.com/docs/messaging/troubleshooting/error-codes.md).

**hangup\_cause** `string`

Rolled-up hangup cause on voice and SIP Trunking rows. See [Hangup Causes](https://plivo.com/docs/voice/troubleshooting/hangup-causes.md).

**error\_reason** `string`

Human-readable label for whichever of `error_code` or `hangup_cause` is set on the row.

#### 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

**from\_date** `string`

Charge window start (ISO-8601 timestamp).

**to\_date** `string`

Charge window end (ISO-8601 timestamp).

**description** `string`

Customer-facing label for the charge. Examples: `Number Charges`, `CNAM Lookup`, `Other Charges`.

**total\_units** `integer`

Number of units billed.

**total\_amount** `float`

Total amount charged. Always positive.

***

## 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_spend`, `total_subaccount_spend`, `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.

### 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](https://plivo.com/docs/account/concepts/ip-whitelisting.md). |
| `429` | Rate limit exceeded. See [Rate limits](#rate-limits). |
| `502` | Upstream service failure. |

### 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.