Usage Summary API

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/

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.

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.

string

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

string

default:"day"

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

string

default:"now − 7 days"

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

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.

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.

string

Filter messaging rows by rolled-up DLR error code. Ignored for non-messaging products. See Error Codes for the full list.

string

Filter voice and SIP Trunking rows by hangup cause. Ignored for other products. See Hangup Causes for the full list.

string

Filter rows by direction. One of inbound or outbound.

string

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

integer

default:"100"

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

string

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

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

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

string

Unique identifier for the request.

object

Summary metadata, window totals, and pagination cursor. See meta below.

array

Paginated telecom-traffic rows for message, voice, zentrunk, and transcription. See usage item below.

array

Non-telecom billing rows — number charges, lookups, fees, taxes, adjustments. See other charges item below.

{
  "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.

string

Unique identifier for the request.

object

Summary metadata, window totals, and pagination cursor. See meta below.

array

Paginated telecom-traffic rows for message, voice, zentrunk, and transcription. See usage item below. All usage filters (product, country, direction, error_code, hangup_cause, subaccount_auth) apply to this array.

array

Non-telecom billing rows — number charges, lookups, fees, taxes, adjustments. See other charges item below.

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.

usage item

string

Bucket start (ISO-8601 timestamp). Inclusive.

string

Bucket end (ISO-8601 timestamp). Exclusive.

string

One of message, voice, zentrunk, or transcription.

string

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

string

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

string

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

string

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

integer

Units for this bucket. The unit depends on the product — see Per-product unit meaning below.

float

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

float

Total charge for the bucket.

float

Surcharge component of total_amount, when applicable.

string

Rolled-up DLR error code on messaging rows. Empty on successful delivery. See Error Codes.

string

Rolled-up hangup cause on voice and SIP Trunking rows. See Hangup Causes.

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

string

Charge window start (ISO-8601 timestamp).

string

Charge window end (ISO-8601 timestamp).

string

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

integer

Number of units billed.

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.

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

cURL

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.
`429`	Rate limit exceeded. See Rate limits.
`502`	Upstream service failure.

Example: window cap exceeded

{
  "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.

Concepts

API Reference

Usage Summary API

Retrieve Usage Summary

Arguments

Window limits per granularity

Example

Response

The Usage Summary Object

meta

usage item

Per-product unit meaning

other charges item

Example: fetching page 2

Rate limits

Response codes

Example: window cap exceeded

Notes

​Retrieve Usage Summary

​Arguments

​Window limits per granularity

​Example

​Response

​The Usage Summary Object

​meta

​usage item

​Per-product unit meaning

​other charges item

​Pagination

​Example: fetching page 2

​Rate limits

​Response codes

​Example: window cap exceeded

​Notes

Retrieve Usage Summary

Arguments

Window limits per granularity

Example

Response

The Usage Summary Object

meta

usage item

Per-product unit meaning

other charges item

Pagination

Example: fetching page 2

Rate limits

Response codes

Example: window cap exceeded

Notes