Skip to main content
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.
​
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 for the full list.
​
hangup_cause
string
Filter voice and SIP Trunking rows by hangup cause. Ignored for other products. See Hangup Causes 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.
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:
GranularityMaximum window
hour7 days
day92 days
month24 months
yearUnlimited (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

{
  "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.
​
api_id
string
Unique identifier for the request.
​
meta
object
Summary metadata, window totals, and pagination cursor. See meta below.
​
usage
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.
​
other_charges
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.

​
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_spent
float
Grand total (usage + other_charges) over the entire reporting window. Returned on page 1 only.
​
total_subaccount_spent
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 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.
​
hangup_cause
string
Rolled-up hangup cause on voice and SIP Trunking rows. See Hangup Causes.
​
error_reason
string
Human-readable label for whichever of error_code or hangup_cause is set on the row.

​
Per-product unit meaning

Producttotal_units meansduration_seconds means
messageMessage segmentsNot returned
voiceCall countBilled call duration
zentrunkCall countBilled call duration
transcriptionTranscription countRecording 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.
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.

​
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

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

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