Usage API guide

The Billing Usage API requires OAuth 2.0 authentication for all requests. All API requests must be authenticated using an OAuth access token.

Before generating a token, create an OAuth application in OneConsole to acquire your client credentials. The application type depends on the scope of the endpoints you intend to query:

• Organization-level applications: Required if you're querying Billing Group-level endpoints.
• Account-level applications: Required if you're querying Account level endpoints.

Ensure your application is explicitly configured with the following permission scope:

twilio/billing-insights/usage/read

This scope grants read access to billing usage data at the appropriate level (organization or account).

Obtain an access token by submitting a request to the token endpoint using your client credentials. Include this access token in the Authorization header of every API request:

Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN

The Billing Usage API provides data you can reconcile with your invoice. It includes:

• Structured JSON payloads: Use POST requests with JSON request bodies to combine date, product, aggregation, and pagination filters for precise query customization.
• Invoice-aligned product taxonomy: The productCategory parameter aligns with the standardized, multi-level product taxonomy used in the Console and billing statements.
• Separated usage and price data: Response payloads clearly separate usage measurements and costs into distinct, structured objects for easier integration.
• Predictable query ranges: A custom date range can cover up to 365 days. Use explicit dates instead of legacy endpoints (such as /Today and /Alltime).
• Token-based pagination: Use nextToken from the response metadata to page through results, replacing legacy page indexing.
• Standardized data freshness: Data updates in predictable 24-hour batches, which keeps intra-month reporting consistent.

Billing Group usage data is retrieved through the Billing Usage API using two complementary methods:

Replace {billingGroupId} with the specific billing_group_ string retrieved from the Console. This ensures the API correctly identifies the billing entity for which you are requesting records.

POST https://billing.twilio.com/v2/Public/Usage/BillingGroups/{billingGroupId}/Records

The request body is a JSON object containing your filter parameters:

1
{
2
  "startOn": "2025-01-01",
3
  "endOn": "2025-01-31",
4
  "productCategory": "sms",
5
  "aggregationPeriod": "DAILY",
6
  "pageSize": 100
7
}

Precise data retrieval makes analysis more effective. By using request parameters, you can isolate specific cost drivers, filter by product categories, and define exact timeframes.

The aggregationPeriod is a critical tool for financial granularity:

• DAILY: Identify specific usage spikes or trends within a month. Vital for spotting anomalies and understanding daily cost drivers. Use daily aggregation when investigating unexpected charges or tracking hour-to-hour changes.
• MONTHLY: Provides a high-level executive view of spend for period-over-period analysis.

The Usage API returns structured output that maps technical usage metrics directly to costs. The response shows what was used, when it was used, and the associated price.

The API returns records with the following properties:

For organizations with high volume usage, managing pagination is critical:

The meta section of the response contains:

• pageSize: The number of records returned in the current response.
• previousToken: Token to retrieve the previous page (if available).
• nextToken: Token to retrieve the next page (if available).

To iterate through all records without missing data:

1. Execute your initial query with your desired filters.
2. Process the records returned in the records array.
3. If meta.nextToken is present, make another request with the same filters. Add "pageToken": "NEXT_TOKEN" to the request body, replacing NEXT_TOKEN with the value of meta.nextToken.
4. Repeat until meta.nextToken is not present or is null.

This token-based pagination replaces legacy page-number indexing and lets you traverse large datasets reliably.

Usage data is updated in batches and may be up to 24 hours behind current activity. The latest available updatedOn value is typically the day before the request date because the current day's data is still being computed. This standardized cadence ensures every record reflects verified billing data, eliminating data drift and intra-day reconciliation discrepancies.

• Billing Groups — Basic guide to Billing Groups and finding your Billing Group ID.
• Billing — Overview of Twilio billing tools and resources.
• Usage records API — REST API reference for usage records.
• Twilio Help Center: Billing — General billing FAQs and account management.
• Billing Group ID: Consolidated Billing and Usage Analytics — Detailed guide to Billing Group IDs and the Usage API.