REST API: Usage Records

The UsageRecords REST resource provides a simple API to retrieve usage made by your Twilio account during any time period and by any usage category. This makes it easy to build reporting and analytics tools for your application. UsageRecords used in combination with Subaccounts created for each of your end-users make it possible to build recurring usage-based billing systems on top of Twilio's API with just a few simple API calls.

You can also set up usage triggers to notify your application when a particular category of usage reaches a threshold on a daily, monthly, yearly, or all-time basis. Triggers can help determine if your users have reached a cap on usage, or if your application may have runaway requests. For more on usage triggers, see the Usage Triggers documentation.

UsageRecords List Resource

Resource URI

/2010-04-01/Accounts/{AccountSid}/Usage/Records

Resource Properties

This resource and its subresources always return a list of UsageRecords. Each UsageRecord is represented by the following properties:

PropertyDescription
CategoryThe category of usage. See Usage Categories below.
DescriptionA human-readable description of the usage category.
AccountSidThe Account that accrued the usage.
StartDateThe first date for which usage is included in this UsageRecord, formatted as YYYY-MM-DD. All dates are in GMT.
EndDateThe last date for which usage is included in this UsageRecord, formatted as YYYY-MM-DD. All dates are in GMT.
UsageThe amount of usage (e.g. the number of call minutes). This is frequently the same as Count, but may be different for certain usage categories like calls, where Count represents the number of calls and Usage represents the number of minutes.
UsageUnitThe units in which Usage is measured. For example minutes for calls, messages for SMS.
CountThe number of usage events (e.g. the number of calls).
CountUnitThe units in which Count is measured. For example calls for calls, messages for SMS.
PriceThe total price of the usage, in the currency associated with the account.
PriceUnitThe currency in which Price is measured, in ISO 4127 format (e.g. usd, eur, jpy).
UriThe URI that returns only this UsageRecord, relative to https://api.twilio.com.
SubresourceUrisSubresource Uris for this UsageRecord. See List Subresources.
Usage, Count, and Price

Each UsageRecord contains three amounts: Usage, Count, and Price. Usage is the primary way usage is measured for that category: minutes for calls, messages for SMS, etc. Count is the number of usage events: calls for calls, etc. And Price is the price of the usage in the currency associated with the account.

Each UsageRecord also has fields that show the units in which each amount is measured: Usage is measured in units of UsageUnit, for instance. These fields make it easy to build usage dashboards. For example, you can always display human-readable strings describing usage with "$Usage $UsageUnits", "$Count $CountUnits", or "$Price $PriceUnits".

Usage Categories

A UsageRecord's Category defines the type of usage it represents. The full list of all categories is here, but you'll usually focus on just a few common categories:

             Category                  Description
callsAll voice calls. Count is the number of calls and Usage is the number of minutes.
smsAll SMS messages. Count and Usage are both the number of messages sent.
phonenumbersAll phone numbers owned by the account.
recordingsRecordings of voice calls. Count is the number of recordings and Usage is the number of recorded minutes. Note that Twilio doesn't charge for making recordings (only storing them long term) so Price will always be 0.
transcriptionsTranscriptions of voice calls. Count is the number of transcriptions and Usage is the number of transcribed minutes.
totalpriceTotal price of all usage. Usage will be the same as Price, and Count will be empty. Note that because some Twilio costs may not be included in any usage category, the sum of the Price of all UsageRecords may not be equal to the Price of TotalPrice.

HTTP GET

Returns UsageRecords for all usage categories. The list includes paging information.

List Filters

By default, the UsageRecords resource will return one UsageRecord for each Category, representing all usage accrued all-time for the account. You can filter the usage Category or change the date-range over which usage is counted using optional GET query parameters. Note that query parameters are case-sensitive:

ParameterDescription
CategoryOnly include usage of this usage category.
StartDateOnly include usage that has occurred on or after this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, StartDate=-30days will make StartDate be 30 days before today.
EndDateOnly include usage that has occurred on or before this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, EndDate=+30days will make EndDate be 30 days from today.

For example, you might request all usage records for the month of April, 2012. In this case, the query string would be StartDate=2012-04-01&EndDate=2012-04-30. This would return one UsageRecord for each usage-type summarizing the usage during April. The list includes paging information. See Example 2 below.

It's also possible to group usage by day, by month, or by year using the subresources described below.

List Subresources

The main UsageRecords list resource supports a variety of convenience subresources. In general these take the form:

/2010-04-01/Accounts/{AccountSid}/Usage/Records/{Subresource}

Supported subresources are:

SubresourceDescription
DailyReturn multiple UsageRecords for each usage category, each representing usage over a daily time-interval.
MonthlyReturn multiple UsageRecords for each usage category, each representing usage over a monthly time-interval.
YearlyReturn multple UsageRecords for each usage category, each representing usage over a yearly time-interval.
AllTimeReturn a single UsageRecord for each usage category, each representing usage over the date-range specified. This is the same as the root /Usage/Records.
TodayReturn a single UsageRecord per usage category, for today's usage only.
YesterdayReturn a single UsageRecord per usage category, for yesterday's usage only.
ThisMonthReturn a single UsageRecord per usage category, for this month's usage only.
LastMonthReturn a single UsageRecord per usage category, for last month's usage only.

These convenience subresources can be used to draw a graph of daily calls, display dashboards of monthly usage across all usage categories, or build a simple usage-based billing system based on last month's usage totals.

All subresources support the same list filters as the root UsageCounters resource.

Example 1: Last Month's Usage for All Usage Categories
Example 2: Today's Calls
Example 3: One-Month Date-Range, Inbound Calls Only
Example 4: Daily Usage for Inbound Calls Over a One-Month Period
Example 5: All-Time Usage, All Usage Categories

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.

Full List of All Usage Categories

The full list of supported usage categories are:

             Category                  Description
callsAll voice calls, inbound & outbound. Count is the number of calls and Usage is the number of minutes.
calls-inboundAll inbound voice calls, to both toll-free and local numbers.
calls-inbound-localAll inbound voice calls to local numbers.
calls-inbound-tollfreeAll inbound voice calls to toll-free numbers.
calls-outboundAll outbound voice calls.
calls-clientAll TwilioClient voice calls.
calls-sipAll SIP calls.
smsAll SMS messages, both inbound and outbound. Count and Usage are both the number of messages sent.
sms-inboundAll inbound SMS messages, to both short-codes and long-codes.
sms-inbound-shortcodeAll inbound SMS messages to short-codes.
sms-inbound-longcodeAll inbound SMS messages to long-codes.
sms-outboundAll outbound SMS messages, from both short-codes and long-codes.
sms-outbound-shortcodeAll outbound SMS messages from short-codes.
sms-outbound-longcodeAll outbound SMS messages from long-codes.
phonenumbersAll phone numbers owned by the account, toll-free and local.
phonenumbers-tollfreeAll toll-free phone numbers owned by the account.
phonenumbers-localAll local phone numbers owned by the account.
shortcodesAll ShortCodes owned by the account, of all types.
shortcodes-vanityAll vanity ShortCodes owned by the account.
shortcodes-randomAll randomly-assigned ShortCodes owned by the account.
shortcodes-customerownedAll ShortCodes owned by the account that are leased from another provider.
calleridlookupsCallerID (CallerName) lookups.
recordingsRecordings of voice calls. Count is the number of recordings and Usage is the number of recorded minutes. Note that Twilio doesn't charge for making recordings (only storing them long term) so Price will always be 0.
transcriptionsTranscriptions of voice calls. Count is the number of transcriptions and Usage is the number of transcribed minutes.
recordingstorageAmount of storage used by call recordings stored for the account. Count is the number of stored recordings, Usage is the number of stored recorded minutes, and Price is the price of storing the recordings.
totalpriceTotal price of all usage. Usage will be the same as Price, and Count will be empty. Note that because some Twilio costs may not be included in any usage category, the sum of the Price in all UsageRecords may or may not be equal to the Price of TotalPrice.

UsageRecords Instance Resource

You cannot make requests directly to a UsageRecord resource. Instead, make a request to the UsageRecords list resource or one of its subresources.