Menu

Expand
Rate this page:

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
sid<AC> Not PII

The SID of the Account that accrued the usage.

api_version
string Not PII

The API version used to create the resource.

as_of
string Not PII

Usage records up to date as of this timestamp, formatted as YYYY-MM-DDTHH:MM:SS+00:00. All timestamps are in GMT

category
enum:category Not PII

The category of usage. For more information, see Usage Categories.

count
string Not PII

The number of usage events, such as the number of calls.

count_unit
string Not PII

The units in which count is measured, such as calls for calls or messages for SMS.

description
string Not PII

A plain-language description of the usage category.

end_date
date<iso8601> Not PII

The last date for which usage is included in the UsageRecord. The date is specified in GMT and formatted as YYYY-MM-DD.

price
decimal Not PII

The total price of the usage in the currency specified in price_unit and associated with the account.

price_unit
currency Not PII

The currency in which price is measured, in ISO 4127 format, such as usd, eur, and jpy.

start_date
date<iso8601> Not PII

The first date for which usage is included in this UsageRecord. The date is specified in GMT and formatted as YYYY-MM-DD.

subresource_uris
uri_map Not PII

A list of related resources identified by their URIs. For more information, see List Subresources.

uri
uri Not PII

The URI of the resource, relative to https://api.twilio.com.

usage
string Not PII

The amount used to bill usage and measured in units described in usage_unit.

usage_unit
string Not PII

The units in which usage is measured, such as minutes for calls or messages for SMS.

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

get
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
get sid<AC> Not PII

The SID of the Account that created the UsageRecord resources to read.

category
Optional
get enum:category Not PII

The usage category of the UsageRecord resources to read. Only UsageRecord resources in the specified category are retrieved.

start_date
Optional
get date<iso8601> Not PII

Only include usage that has occurred on or after this date. Specify the date in GMT and format as YYYY-MM-DD. You can also specify offsets from the current date, such as: -30days, which will set the start date to be 30 days before the current date.

end_date
Optional
get date<iso8601> Not PII

Only include usage that occurred on or before this date. Specify the date in GMT and format as YYYY-MM-DD. You can also specify offsets from the current date, such as: +30days, which will set the end date to 30 days from the current date.

include_subaccounts
Optional
get boolean Not PII

Whether to include usage from the master account and all its subaccounts. Can be: true (the default) to include usage from the master account and all subaccounts or false to retrieve usage from only the specified account.

Example 1
Loading Code Sample...
        
        

        Last Month’s Usage for All Usage Categories

        Example 2
        Loading Code Sample...
              
              

              Today’s Calls

              Example 3
              Loading Code Sample...
                    
                    

                    One-Month Date-Range, Inbound Calls Only

                    Example 4
                    Loading Code Sample...
                          
                          

                          Daily Usage for Inbound Calls Over a One-Month Period

                          Example 5
                          Loading Code Sample...
                                
                                

                                All-Time Usage, All Usage Categories

                                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.
                                tts-google Speech generated with Google voices.
                                virtual-agent Virtual Agent usage in calls. Count is the number of <VirtualAgent> invocations and Usage is the number of minutes.
                                voice-intelligence All Voice Intelligence transcriptions and language operators minutes
                                voice-intelligence-transcription Voice Intelligence transcriptions minutes
                                voice-intelligence-operators Voice Intelligence language operators 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. See our pricing page for details.
                                channels-whatsapp-inbound User-initiated conversation fees are charged on a business' first response to user messages. See our pricing page for details.
                                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.
                                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.

                                Rate this page:

                                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.

                                Loading Code Sample...
                                      
                                      
                                      

                                      Thank you for your feedback!

                                      Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                      Sending your feedback...
                                      🎉 Thank you for your feedback!
                                      Something went wrong. Please try again.

                                      Thanks for your feedback!

                                      thanks-feedback-gif