REST API: Usage Records
The UsageRecords resource provides a simple API to retrieve actions 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. If rectifying UsageRecords with billing, see our dedicated article.
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 has runaway requests.
UsageRecord properties
This resource and its subresources always return a list of UsageRecords. Each UsageRecord is represented by the following properties:
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The SID of the Account that accrued the usage. |
api_version
|
The API version used to create the resource. |
as_of
|
Usage records up to date as of this timestamp, formatted as YYYY-MM-DDTHH:MM:SS+00:00. All timestamps are in GMT |
category
|
The category of usage. For more information, see Usage Categories. |
count
|
The number of usage events, such as the number of calls. |
count_unit
|
The units in which |
description
|
A plain-language description of the usage category. |
end_date
|
The last date for which usage is included in the UsageRecord. The date is specified in GMT and formatted as |
price
|
The total price of the usage in the currency specified in |
price_unit
|
The currency in which |
start_date
|
The first date for which usage is included in this UsageRecord. The date is specified in GMT and formatted as |
subresource_uris
|
A list of related resources identified by their URIs. For more information, see List Subresources. |
uri
|
The URI of the resource, relative to |
usage
|
The amount used to bill usage and measured in units described in |
usage_unit
|
The units in which |
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. 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 |
|---|---|
| calls | Inbound and outbound voice calls. Does not include SIP or client calls. Count is the number of calls and Usage is the number of minutes. |
| sms | All SMS messages. Count and Usage are both the number of messages sent. |
| pfax-minutes | Programmable Fax minutes. Count is the number of faxes and Usage is the number of minutes. |
| pfax-pages | Programmable Fax pages. Count is the number of faxes and Usage is the number of pages. |
| phonenumbers | All phone numbers owned by the account. |
| recordings | Recordings of voice calls. Count is the number of recordings and Usage is the number of recorded minutes. |
| transcriptions | Transcriptions of voice calls. Count is the number of transcriptions and Usage is the number of transcribed minutes. |
| pv | All Programmable Video usage including TURN. Price accounts for expenses in all Programmable Video products. Count and Usage should be ignored. |
| totalprice | Total 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. |
Read multiple UsageRecord resources
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Records.json
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:
Parameters
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the UsageRecord resources to read. |
category
Optional
|
The usage category of the UsageRecord resources to read. Only UsageRecord resources in the specified category are retrieved. |
start_date
Optional
|
Only include usage that has occurred on or after this date. Specify the date in GMT and format as |
end_date
Optional
|
Only include usage that occurred on or before this date. Specify the date in GMT and format as |
include_subaccounts
Optional
|
Whether to include usage from the master account and all its subaccounts. Can be: |
Example 1
Example 2
Example 3
Example 4
Example 5
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.
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:
| Subresource | Description |
|---|---|
| Daily | Return multiple UsageRecords for each usage category, each representing usage over a daily time-interval. |
| Monthly | Return multiple UsageRecords for each usage category, each representing usage over a monthly time-interval. |
| Yearly | Return multple UsageRecords for each usage category, each representing usage over a yearly time-interval. |
| AllTime | Return a single UsageRecord for each usage category, each representing usage over the date-range specified. This is the same as the root /Usage/Records. |
| Today | Return a single UsageRecord per usage category, for today’s usage only. |
| Yesterday | Return a single UsageRecord per usage category, for yesterday’s usage only. |
| ThisMonth | Return a single UsageRecord per usage category, for this month’s usage only. |
| LastMonth | Return 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.
Full List of All Usage Categories
Voice
| Category | Description |
|---|---|
| agent-conference | Count is the number of agent conferences and Usage is the number of minutes. |
| answering-machine-detection | All answering machine detection recognitions for outbound calls. Count is the number of recognitions. |
| amazon-polly | Speech generated with Polly voices. |
| calls | Inbound and outbound voice calls. Count is the number of calls and Usage is the number of minutes. Does not include client or SIP calls. |
| calls-inbound | All inbound voice calls, to mobile, toll-free and local numbers. |
| calls-inbound-local | All inbound voice calls to local numbers. |
| calls-inbound-mobile | All inbound voice calls to mobile numbers. |
| calls-inbound-tollfree | All inbound voice calls to toll-free numbers. |
| calls-outbound | All outbound voice calls. |
| calls-sip | All SIP calls. |
| calls-sip-inbound | All inbound SIP calls. |
| calls-sip-outbound | All outbound SIP calls. |
| calls-client | All TwilioClient voice calls. |
| calls-globalconference | All global conference calls. |
| calls-media-stream-minutes | All Media Stream calls |
| calls-pay-verb-transactions | <Pay> verb transactions. Count is total number of <Pay> transactions |
| call-progess-events | All call progress events. |
| calls-recordings | Recordings of voice calls. Count is the number of recordings and Usage is the number of recorded minutes. |
| programmablevoice-platform | All Programmable Voice Platform usage in Flex Projects |
| programmablevoiceconnectivity | Inbound and outbound voice calls in Flex Projects. Count is the number of calls and Usage is the number of minutes. Includes Client and SIP Calls. |
| programmablevoiceconn-sip | All SIP Calls in Flex Projects |
| programmablevoiceconn-sip-inbound | All Inbound SIP Calls in Flex Projects |
| programmablevoiceconn-sip-outbound | All Outbound SIP Calls in Flex Projects |
| programmablevoiceconn-clientsdk | All TwilioClient voice calls in Flex Projects |
| pstnconnectivity | Inbound and outbound voice calls in Flex Projects. Count is the number of calls and Usage is the number of minutes. |
| pstnconnectivity-inbound | All inbound voice calls, to mobile, toll-free and local numbers in Flex Projects |
| pstnconnectivity-outbound | All oubound voice calls in Flex Projects |
| recordings | Recordings of voice and trunking calls. Count is the number of recordings and Usage is the number of recorded minutes. |
| recordingstorage | Amount 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. |
| speech-recognition | Speech recognitions in calls. Count is total number of calls where speech recognition was performed and usage is total number of recognitions |
| transcriptions | Transcriptions of voice calls. Count is the number of transcriptions and Usage is the number of transcribed minutes. |
| virtual-agent | Virtual Agent usage in calls. Count is the number of <VirtualAgent> invocations and Usage is the number of minutes. |
| voice-insights | Voice Insights Advanced Features |
| voice-insights-ptsn-insights-on-demand-minute | Voice Insights Advanced Features for Programmable Voice calls |
| voice-insights-sip-trunking-insights-on-demand-minute | Voice Insights Advanced Features for Elastic SIP Trunking calls. |
SMS & MMS
| Category | Description |
|---|---|
| a2p-registration-fees | All Messaging A2P Registration Fees |
| sms | All SMS messages, both inbound and outbound. Count and Usage are both the number of messages sent. |
| sms-inbound | All inbound SMS messages, to both short-codes and long-codes. |
| sms-inbound-longcode | All inbound SMS messages to long-codes. |
| sms-inbound-shortcode | All inbound SMS messages to short-codes. |
| sms-outbound | All outbound SMS messages, from both short-codes and long-codes. |
| sms-outbound-longcode | All outbound SMS messages from long-codes. |
| sms-outbound-shortcode | All outbound SMS messages from short-codes. |
| sms-messages-carrierfees | All carrier fees for SMS messages. |
| mms | All MMS messages, both inbound and outbound. Count and Usage are both the number of messages sent. |
| mms-inbound | All inbound MMS messages, to both short-codes and long-codes. |
| mms-inbound-longcode | All inbound MMS messages to long-codes. |
| mms-inbound-shortcode | All inbound MMS messages to short-codes. |
| mms-outbound | All outbound MMS messages, from both short-codes and long-codes. |
| mms-outbound-longcode | All outbound MMS messages from long-codes. |
| mms-outbound-shortcode | All outbound MMS messages from short-codes. |
| mms-messages-carrierfees | All carrier fees for MMS messages. |
| mediastorage | Amount of storage used by media stored for the account. Count is the number of stored media files, Usage is the number of megabytes, and Price is the price of storing the media. |
WhatsApp Business API
| Category | Description |
|---|---|
| channels-whatsapp-outbound | WhatsApp Conversations Fees. WhatsApp charges per user - or business-initiated conversation in 24-hour increments that start when the first message from a business is delivered. This price depends on the destination country. See our pricing page for details. |
| channels-whatsapp-inbound | WhatsApp does not charge for inbound messages. This cost will always be zero. User-initiated conversation fees are charged on business' first response to user messages. |
| channels-messaging-inbound | Twilio charges a flat-rate per inbound message platform fee for any and all countries. |
| channels-messaging-outbound | Twilio charges a flat-rate per outbound message platform fee for any and all countries. |
Twilio Conversations
| Category | Description |
|---|---|
| pchat-users | Active Monthly Users - An active user is defined as someone who creates a user or conversation, or edits, or is assigned to a conversation. This includes reading conversations, sending messages in a chat view, or sending and receiving SMS and WhatsApp messages via the Conversations product. |
| pchat-conv-med-storage | Media Storage - Photos, videos, or other files stored and distributed in Conversations are billed at a monthly rate according to their size, prorated daily. Only stored media (pictures, videos, etc.) incurs a charge; ordinary text-only message bodies are stored at no cost. |
Phone Numbers
| Category | Description |
|---|---|
| phonenumbers | All phone numbers owned by the account, mobile, toll-free and local. |
| phonenumbers-local | All local phone numbers owned by the account. |
| phonenumbers-mobile | All mobile phone numbers owned by the account. |
| phonenumbers-tollfree | All toll-free phone numbers owned by the account. |
| phonenumbers-cps | All phone number call per second (CPS) increases. |
| phonenumbers-setups | All phone number setups fees. |
| shortcodes | All ShortCodes owned by the account, of all types. |
| shortcodes-customerowned | All ShortCodes owned by the account that are leased from another provider. |
| shortcodes-mms-enablement | All Short Code MMS enablement fees. |
| shortcodes-mps | All Short Code message per second (MPS) increases. |
| shortcodes-random | All randomly-assigned ShortCodes owned by the account. |
| shortcodes-uk | All UK ShortCodes owned by the account. |
| shortcodes-vanity | All vanity ShortCodes owned by the account. |
Lookup
| Category | Description |
|---|---|
| lookups | All Lookups executed across all categories |
| carrier-lookups | All Carrier lookups |
| calleridlookups | All Caller Name lookups |
| number-format-lookups | All Number Formatting lookups |
| call-forwarding-lookups | All Call Forwarding lookups |
| sim-swap-lookups | All SIM Swap lookups |
| live-activity-lookups | All Live Activity lookups |
| enhanced-line-type-lookups | All Line Type Intelligence lookups |
| identity-match | All Identity Match lookups |
Elastic SIP Trunking
| Category | Description |
|---|---|
| trunking-origination | All trunking origination (inbound) calls, to mobile, toll-free and local numbers. |
| trunking-origination-local | All trunking origination (inbound) calls to local numbers. |
| trunking-origination-mobile | All trunking origination (inbound) calls to mobile numbers. |
| trunking-origination-tollfree | All trunking origination (inbound) calls to toll-free numbers. |
| trunking-termination | All trunking termination (outbound) calls. |
| trunking-recordings | Recordings of trunking calls. Count is the number of recordings and Usage is the number of recorded minutes. |
| trunking-cps | All trunking call per second (CPS) increases. |
| trunking-secure | All secured trunking calls. |
| voice-insights-sip-trunking-insights-on-demand-minute | Voice Insights Advanced Features for trunking calls |
Sync
| Category | Description |
|---|---|
| sync-actions | All incoming requests from your application that read and write data. It means actions include any read or write from an SDK or the REST API. Resulting webhooks, updates to connected endpoints, and storage are included in the cost of an action. |
| sync-endpoint-hours | An endpoint-hour is counted once per wall-clock hour for each unique device connected to Sync. Endpoints can be unique devices or browser tabs. Each unique endpoint will incur charges for at most four hours of every calendar day; the remainder are free of charge. |
| sync-endpoint-hours-above-daily-cap | All hours spent above four hours limit are shown separately. All these hours are free of charge. |
Task Router
| Category | Description |
|---|---|
| taskrouter-tasks | All tasks created in Task Router. |
Programmable Video
| Category | Description |
|---|---|
| pv | All Programmable Video usage including TURN. Price accounts for expenses in all Programmable Video products. Count and Usage should be ignored. |
| group-rooms | Accounts for all Group Rooms usage. Count is the number of rooms. Usage should be ignored. |
| group-rooms-participant-minutes | All participant usage in Group Rooms. Count and Usage measure the number of participant minutes. |
| group-rooms-data-track | All Group Room Data Tracks activity. Count and Usage measure thousands of messages sent. |
| small-group-rooms | Accounts for all Small Group Rooms usage. Count is the number of rooms. Usage should be ignored. |
| small-group-rooms-participant-minutes | All participant usage in Small Group Rooms. Count and Usage measure the number of participant minutes. |
| small-group-rooms-data-track | All Small Group Room Data Tracks activity. Count and Usage measure thousands of messages sent. |
| pv-rooms | Accounts for all Peer-to-Peer Rooms usage. Count is the number of rooms. Usage is the number of participant minutes. |
| peer-to-peer-rooms-participant-minutes | All participant usage in P2P Rooms. Count and Usage measure the number of participant minutes. |
| video-recordings | All usage regarding video Recordings and Compositions. Count and Usage should be ignored. |
| group-rooms-recorded-minutes | All Recordings generated out of Group Rooms (including Small Group Rooms). Count and Usage measure the number of recorded participant minutes. |
| pv-composition-minutes | All Video Recording Compositions. Count and Usage measure the number of composition minutes. |
| group-rooms-encrypted-media-recorded | All encrypted media including Group Room Recordings and Compositions. Count and Usage measure the number of encrypted participant minutes and composition minutes. |
| group-rooms-media-stored | All media stored in Twilio by Programmable Video Services including Recordings and Compositions. Count and Usage measure the number of stored GB/day (Gigabytes per day). |
| group-rooms-media-downloaded | All media downloaded from Twilio regarding Programmable Video Services. This includes Recordings and Compositions. Count and Usage measure the number of downloaded GB (Gigabytes). |
| turnmegabytes | All TURN data relayed by Twilio. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-australia | TURN data relayed by Twilio in the Australia AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-brasil | TURN data relayed by Twilio in the Brazil AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-india | TURN data relayed by Twilio in the India AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-ireland | TURN data relayed by Twilio in the Ireland AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-japan | TURN data relayed by Twilio in the Japan AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-singapore | TURN data relayed by Twilio in the Singapore AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-useast | TURN data relayed by Twilio in the US (East) AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-uswest | TURN data relayed by Twilio in the US (West) AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-germany | TURN data relayed by Twilio in the Germany AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
Programmable Chat
| Category | Description |
|---|---|
| pchat-users | Active Monthly Users - An active user is defined as someone who creates a user or conversation, or edits, or is assigned to a chat channel. This includes reading conversations or sending messages. |
| pchat-conv-med-storage | Media Storage - Photos, videos, or other files stored and distributed in chat channels are billed at a monthly rate according to their size, prorated daily. Only stored media (pictures, videos, etc.) incurs a charge; ordinary text-only message bodies are stored at no cost. |
Verify
| Category | Description |
|---|---|
| verify-push | All Verify push verifications. Each verification is defined as a challenge that is updated with a status of approved or denied. |
| verify-totp | All Verify TOTP verifications. Each verification is defined as a challenge that is updated with a status of approved. |
| verify-sna | All Verify Silent Network Auth (SNA) verifications. |
| authy-phone-verifications | All Verify SMS and Voice verifications. |
| authy-verify-email-verifications | All Verify email verifications. |
| authy-verify-outbound-email | All Verify one-time tokens requested to be delivered via email. |
| verify-whatsapp-conversations-business-initiated | All WhatsApp business-initiated conversations associated with using Verify to send one-time-passcode messages to WhatsApp users. |
Authy
| Category | Description |
|---|---|
| authy-authentications | All Authy authentications. |
| authy-calls-outbound | All Authy outbound calls. Note that this usage is also included in the Voice categories. |
| authy-monthly-fees | All Authy monthly fees. |
| authy-phone-intelligence | All Authy phone intelligence requests. |
| authy-sms-outbound | All Authy and Verify outbound SMS messages. Note that this usage is also included in the SMS categories. |
| authy-outbound-email | All Authy one-time tokens requested to be delivered via email. |
Studio
| Category | Description |
|---|---|
| studio-engagements | All Studio Engagements |
Monitor
| Category | Description |
|---|---|
| monitor-reads | All Monitor events API reads. |
| monitor-writes | All Monitor events writes. |
| monitor-storage | All Monitor events storage fees. |
Internet of Things
| Category | Description |
|---|---|
| wireless-orders-starter | All Programmable Wireless Starter Packs ordered. |
| wireless-orders-bulk | All Programmable Wireless Bulk SIMs ordered. |
| wireless-mrc-payg | All Programmable Wireless Monthly Fees for SIMs using PAYG data metering. |
Autopilot
| Category | Description |
|---|---|
| autopilot-messaging | All Autopilot messages. Includes messages coming from Programmable Messaging, Programmable Chat and custom channels. |
| autopilot-voice | All Autopilot voice minutes. Count is the number of minutes. |
| autopilot-other | All Autopilot API Queries. Count is the number of queries. |
| autopilot-home-assistants | All messages from Alexa or Google Assistant. |
Event Streams
| Category | Description |
|---|---|
| events | All Event Streams events delivered. Usage is in thousands of events. |
Other
| Category | Description |
|---|---|
| premiumsupport | All premium support fees. |
| totalprice | Total 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.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
