Menu

Expand
Rate this page:

UsageRecord Resource

BETA

Usage Records for Super SIM is currently in Public Beta. Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Beta products are not covered by a Twilio SLA. Learn more about beta product support.

To avoid ambiguity throughout this page, Sim (initial cap) refers to the Sim API resource. SIM (all caps) refers to the physical Subscriber Identity Module (that is, a SIM card) associated with a Sim resource.

A UsageRecord represents aggregated usage information over a specified period. Usage data can be filtered to show usage for a specific resource (e.g., one Super SIM or Network) or grouped around a type of resource (e.g., Sims or Networks) where one record will be returned for each resource of that type for which usage occurred during the requested period. If you want to slice up your results by UTC day or UTC hour, you can control the granularity of the results.

All dates and times are presented in UTC.

The amounts in UsageRecords are presented in the period when the usage occurred, not when it was received and processed by Twilio. This is to better associate the information from this resource with real-world events.

UsageRecord properties

Resource Properties in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that incurred the usage.

sim_sid
sid<HS> Not PII

SID of a Sim resource to which the UsageRecord belongs. Value will only be present when either a value for the Sim query parameter is provided or when UsageRecords are grouped by sim. Otherwise, the value will be null.

network_sid
sid<HW> Not PII

SID of the Network resource the usage occurred on. Value will only be present when either a value for the Network query parameter is provided or when UsageRecords are grouped by network. Otherwise, the value will be null.

fleet_sid
sid<HF> Not PII

SID of the Fleet resource the usage occurred on. Value will only be present when either a value for the Fleet query parameter is provided or when UsageRecords are grouped by fleet. Otherwise, the value will be null.

iso_country
iso_country_code Not PII

Alpha-2 ISO Country Code that the usage occurred in. Value will only be present when either a value for the IsoCountry query parameter is provided or when UsageRecords are grouped by isoCountry. Otherwise, the value will be null.

period
object Not PII

The time period for which the usage is reported. The period is represented as a pair of start_time and end_time timestamps specified in ISO 8601 format.

data_upload
long Not PII

Total data uploaded in bytes, aggregated by the query parameters.

data_download
long Not PII

Total data downloaded in bytes, aggregated by the query parameters.

data_total
long Not PII

Total of data_upload and data_download.

Read UsageRecord resources

get
https://supersim.twilio.com/v1/UsageRecords

Retrieve a list of UsageRecords over a specified period aggregated according to the specified granularity.

Parameters
Parameters in REST API format
sim
Optional
get sid_like<HS> Not PII

SID or unique name of a Sim resource. Only show UsageRecords representing usage incurred by this Super SIM.

fleet
Optional
get sid_like<HF> Not PII

SID or unique name of a Fleet resource. Only show UsageRecords representing usage for Super SIMs belonging to this Fleet resource at the time the usage occurred.

network
Optional
get sid<HW> Not PII

SID of a Network resource. Only show UsageRecords representing usage on this network.

iso_country
Optional
get iso_country_code Not PII

Alpha-2 ISO Country Code. Only show UsageRecords representing usage in this country.

group
Optional
get ienum:group Not PII

Dimension over which to aggregate usage records. Can be: sim, fleet, network, isoCountry. Default is to not aggregate across any of these dimensions, UsageRecords will be aggregated into the time buckets described by the Granularity parameter.

granularity
Optional
get ienum:granularity Not PII

Time-based grouping that UsageRecords should be aggregated by. Can be: hour, day, or all. Default is all. all returns one UsageRecord that describes the usage for the entire period.

start_time
Optional
get date_time<iso8601> Not PII

Only include usage that occurred at or after this time, specified in ISO 8601 format. Default is one month before the end_time.

end_time
Optional
get date_time<iso8601> Not PII

Only include usage that occurred before this time, specified in ISO 8601 format. Default is the current time.

Single SIM Usage Requests versus Account Usage Requests

Queries that are made for a single SIM by passing in a value for the Sim parameter require less computational work to aggregate the results than do requests which encompass all SIMs on your Account. Therefore queries for a single SIM may support longer ranges between the StartTime and EndTime parameters or may support queries made for any valid UTC timestamp as opposed to requiring the timestamps fall on a UTC hour or day boundary. Consequently, the sections below may be read in two ways, each depending on whether the request you are making is a Single SIM Usage Request or an Account Usage Request:

  • Single SIM Usage Requests — These are requests made with the Sim parameter set. They return UsageRecords representing usage only incurred by that Super SIM.
  • Account Usage Requests — These are requests made without any Sim parameter set. They return UsageRecords representing usage incurred by all Super SIMs in your Account.

Read filtered UsageRecords

You can filter UsageRecords to show usage for a specific resource such as a single SIM or Network.

The following query parameters will give you filtered UsageRecords:

  • Sim — Only show usage for the requested Sim resource. Can be passed in as either the Sim resource’s Sid or UniqueName.
  • Fleet — Only show usage for Super SIMs that were assigned to this Fleet resource when the usage occurred. Can be passed in as either the Fleet resource’s Sid or UniqueName.
  • Network — Only show usage on this cellular network. Only accepts the Network resource’s Sid as FriendlyNames are subject to change.
  • IsoCountry — Only show usage incurred on cellular networks in this country. IsoCountry will be determined based on the IsoCountry of the Network resource on which the usage occurred.

When a filter is applied, the corresponding parameter on each UsageRecord will be populated with this value. For example, if you filter by a Sim resource, each UsageRecord returned will have the Sim resource’s Sid in the SimSid property.

Multiple filters can be applied at once. For example, you can provide values for both Sim and Network to see the usage that a single Super SIM incurred on the requested cellular network.

Read UsageRecords over time

Each UsageRecord will represent the usage incurred over a period of time. The unit of time that each record represents depends on the Granularity query parameter. You can set the Granularity to either all, day, or hour. The default value is all.

The maximum allowed range between the StartTime and EndTime will vary depending on the Granularity you select and whether or not you are making a Single SIM Usage Request or an Account Usage Request. Further limitations on the allowed range may be imposed if you group your UsageRecords by a resource type as documented in the Group UsageRecords by resource type section below.

Single SIM Usage Requests

Requests for the usage incurred by a single SIM must be made using the following rules for each Granularity:

  • all — One record will be returned representing the usage for the entire period between the StartTime and EndTime. Your StartTime and EndTime request parameters can be any valid UTC timestamp. The maximum allowed query period is 18 months.
  • day — One record will be returned for each UTC day between the StartTime and EndTime (exclusive). Your StartTime and EndTime request parameters must fall on midnight UTC (e.g., 2021-08-19T00:00:00Z) when Granularity=day or they will be rejected. The maximum allowed query period is 3 months.
  • hour — One record will be returned for each UTC hour between the StartTime and EndTime (exclusive). Your StartTime and EndTime request parameters must fall on a UTC hour (e.g., 2021-08-19T03:00:00Z) when Granularity=hour or they will be rejected. The maximum allowed query period is 31 days.

Account Usage Requests

Requests for the usage incurred by all the Super SIMs in your Account must be made using the following rules for each Granularity:

  • all — One record will be returned representing the usage for the entire period between the StartTime and EndTime. Your StartTime and EndTime request parameters must fall on a UTC hour (e.g., 2021-08-19T03:00:00Z) when Granularity=all or they will be rejected. The maximum allowed query period is 18 months.
  • day — One record will be returned for each UTC day between the StartTime and EndTime (exclusive). Your StartTime and EndTime request parameters must fall on midnight UTC (e.g., 2021-08-19T00:00:00Z) when Granularity=day or they will be rejected. The maximum allowed query period is 3 months.
  • hour — One record will be returned for each UTC hour between the StartTime and EndTime (exclusive). Your StartTime and EndTime request parameters must fall on a UTC hour (e.g., 2021-08-19T03:00:00Z) when Granularity=hour or they will be rejected. The maximum allowed query period is 31 days.
Example 1
        
        
        
        Retrieve the aggregated usage for the entire period.

        Read a UsageRecord

        Retrieve the aggregated usage for the entire period.
        Example 2
              
              
              
              Retrieve usage aggregated by day.

              Read daily UsageRecords

              Retrieve usage aggregated by day.
              Example 3
                    
                    
                    
                    Retrieve usage aggregated by hour.

                    Read hourly UsageRecords

                    Retrieve usage aggregated by hour.
                    Example 4
                          
                          
                          
                          Read the usage for a single Super SIM by day.

                          Read daily UsageRecords for a SIM

                          Read the usage for a single Super SIM by day.
                          Example 5
                                
                                
                                
                                Read the usage for all Super SIMs in a single Fleet by day.

                                Read daily UsageRecords for a Fleet

                                Read the usage for all Super SIMs in a single Fleet by day.
                                Example 6
                                      
                                      
                                      
                                      Read the usage incurred on a single network by day

                                      Read daily UsageRecords for a Network

                                      Read the usage incurred on a single network by day
                                      Example 7
                                            
                                            
                                            
                                            Read the usage incurred on all networks in a single country by day.

                                            Read daily UsageRecords for a country

                                            Read the usage incurred on all networks in a single country by day.

                                            Group UsageRecords by resource type

                                            You can group UsageRecords around a type of resource (e.g., Sims or Networks). Each UsageRecord represents the aggregated usage incurred by an instance of the resource (e.g. a Sim or a Network) over a period of time.

                                            Grouping your UsageRecords by SIM or by Fleet is currently in Private Beta. To request access to this functionality, contact your Twilio Account Executive or Twilio Support at help-wireless@twilio.com.

                                            You can group your UsageRecords by the following resource types:

                                            • sim — Group usage by Super SIM. Each UsageRecord represents the usage incurred by a Sim resource over the UsageRecord’s period. When grouping usage by Super SIM, the maximum allowed query period between the StartTime and EndTime is 31 days for all Granularity values. This functionality is in Private Beta and you may need it unlocked on your Twilio Account.
                                            • fleet — Group usage by Fleet. Each UsageRecord represents the usage incurred by all the Super SIMs assigned to a Fleet resource when the usage occurred over the UsageRecord’s period. This functionality is in Private Beta and you may need it unlocked on your Twilio Account.
                                            • network — Group usage by Network. Each UsageRecord represents the usage incurred on a Network resource over the UsageRecord’s period.
                                            • isoCountry — Group usage by country. Each UsageRecord represents the usage incurred on all of the Network resources in a country over the UsageRecord’s period.

                                            When a grouping is applied, the corresponding resource type’s parameter on each UsageRecord will be populated with its identifier. For example, if you group by sim, each UsageRecord returned will have the Sim resource’s Sid in the SimSid property.

                                            You can filter grouped UsageRecords.

                                            Example 8
                                                  
                                                  
                                                  
                                                  Read the usage for multiple Super SIMs.

                                                  Read grouped SIM UsageRecords

                                                  Read the usage for multiple Super SIMs.
                                                  Example 9
                                                        
                                                        
                                                        
                                                        Read the usage for multiple Fleets.

                                                        Read grouped Fleet UsageRecords

                                                        Read the usage for multiple Fleets.
                                                        Example 10
                                                              
                                                              
                                                              
                                                              Read the usage for multiple Networks.

                                                              Read grouped Network UsageRecords

                                                              Read the usage for multiple Networks.
                                                              Example 11
                                                                    
                                                                    
                                                                    
                                                                    Read the usage for multiple Countries.

                                                                    Read grouped country UsageRecords

                                                                    Read the usage for multiple Countries.
                                                                    Example 12
                                                                          
                                                                          
                                                                          
                                                                          Read the usage for multiple Super SIMs in a single country.

                                                                          Read grouped SIM UsageRecords for a country

                                                                          Read the usage for multiple Super SIMs in a single country.
                                                                          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 Community Forums or browsing the Twilio tag on Stack Overflow.

                                                                                
                                                                                
                                                                                

                                                                                Thank you for your feedback!

                                                                                We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

                                                                                Thanks for your feedback!

                                                                                Refer us and get $10 in 3 simple steps!

                                                                                Step 1

                                                                                Get link

                                                                                Get a free personal referral link here

                                                                                Step 2

                                                                                Give $10

                                                                                Your user signs up and upgrade using link

                                                                                Step 3

                                                                                Get $10

                                                                                1,250 free SMSes
                                                                                OR 1,000 free voice mins
                                                                                OR 12,000 chats
                                                                                OR more