Skip to navigation
API referenceUsage

Read quantity usage

Separate from request counts and billing. UTC [start,end), maximum 93 days. ID-list filters use repeated query names. Raw supplied ID count across fields is at most 100. Cursor binds normalized filters; filtered lists are not exact batch retrieval. Supports repeated agents and calls. Filter facts before aggregation. group_by=agent adds agent identity and group_by=call adds call identity; omission combines them. No cost/invoice amounts. For more than 100 ID values or call grouping, use POST /usage/query.

Authentication

AuthorizationBearer

Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.

Query parameters

limitintegerOptional1-200Defaults to 50

Page size; 50 by default, at most 200.

cursorstringOptional
Opaque cursor bound to the workspace, every filter, grouping and limit. Send them unchanged with it. Expires after 24 hours.
startdatetimeOptional
Inclusive UTC timestamp. Range must be at most 93 days.
enddatetimeOptional
Exclusive UTC timestamp. Default range is trailing 30 days.
componentlist of stringsOptional

Exact metering component filter, such as telephony or stt. Component vocabulary is open; unsupported filters return 400 rather than silently returning all data. Repeat for OR within this field; AND with other fields. These are not ID entries; at most 32 values per field, the same bound as the POST form. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.

call_idlist of stringsOptional

Repeat the query name for multiple IDs. OR within this field; AND across fields. Maximum 100 raw ID entries total across all ID filters. Blank values are invalid. Unknown/inaccessible IDs produce no rows, not an existence disclosure. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.

agent_idlist of stringsOptional

Repeat the query name for multiple IDs. OR within this field; AND across fields. Maximum 100 raw ID entries total across all ID filters. Blank values are invalid. Unknown/inaccessible IDs produce no rows, not an existence disclosure. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.

group_bylist of enumsOptional

Repeat for several groupings. Omitted combines matching facts by component and unit. agent adds agent_id; call adds call_id. No other dimensions. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.

Allowed values:

Response headers

X-Request-IdstringOptional
Safe server request correlation ID.
RateLimit-LimitintegerOptional
Requests allowed in the current window for the tightest applicable limit.
RateLimit-RemainingintegerOptional
Requests left in the current window.
RateLimit-ResetintegerOptional
Seconds until the current window resets.

Response

Read quantity usage.
statestring

Open response vocabulary. Preserve unknown values; never assume they mean success.

itemslist of objects
next_cursorstring or null
rangeobject

The resolved UTC [start, end) range used, including defaults (trailing 30 days ending now).

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error