メニュー

Expand
Rate this page:

Thanks for rating this page!

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

UsageRecord Resource

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 (eg. one Super SIM or Network) or grouped around a type of resource (eg. SIMs or Networks) where one record will be returned for each resource of that type for which usage occurred during the requested period.

If UsageRecords are not grouped by a resource type, each record will represent a period of time (eg. an hour or a day) depending on the granularity indicated in the request. 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, 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
オブジェクト 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 user-provided granularity.

パラメーター
Parameters in REST API format
sim
オプション
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
オプション
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
オプション
GET sid<HW> Not PII

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

iso_country
オプション
GET iso_country_code Not PII

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

group
オプション
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
オプション
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
オプション
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
オプション
GET date_time<iso8601> Not PII

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

Read UsageRecords over time

If you do not group UsageRecords by a resource type, each recourd will represent a period of time. The unit of time that each record represents depends on the Granularity query parameter. The following values can be passed as the request’s Granularity:

  • all — One record will be returned representing the usage for the entire period between the StartTime and EndTime.
  • day — One record will be returned for each UTC day between the StartTime and EndTime. Each record will start inclusively and end exclusively at midnight UTC.
  • hour — One record will be returned for each UTC hour between the StartTime and EndTime.
例 1
        
        
        
        
        Retrieve the aggregated usage for the entire period.

        Read a UsageRecord

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

              Read Daily UsageRecords

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

                    Read Hourly UsageRecords

                    Retrieve usage aggregated by hour.

                    Read filtered UsageRecords

                    You can filter UsageRecord resources to show usage for a specific resource such as for a single Sim resource or a single Network. If you do not group UsageRecords by a resource type, the UsageRecords will grouped over time based on the Granularity query parameter.

                    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.

                    例 4
                          
                          
                          
                          
                          Read the usage for a single Super SIM.

                          Read Usage Records for a SIM

                          Read the usage for a single Super SIM.
                          例 5
                                
                                
                                
                                
                                Read the usage for a single Super SIM by day.

                                Read Daily Usage Records for a SIM

                                Read the usage for a single Super SIM by day.
                                例 6
                                      
                                      
                                      
                                      
                                      Read the usage for all Super SIMs in a single Fleet.

                                      Read Usage Records for a Fleet

                                      Read the usage for all Super SIMs in a single Fleet.
                                      例 7
                                            
                                            
                                            
                                            
                                            Read the usage incurred on a single network.

                                            Read Usage Records for a Network

                                            Read the usage incurred on a single network.
                                            例8
                                                  
                                                  
                                                  
                                                  
                                                  Read the usage incurred on all networks in a single country.

                                                  Read Usage Records for a Country

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

                                                  Group UsageRecords by resource type

                                                  You can group UsageRecords around a type of resource (eg. SIMs or Networks). Each UsageRecord represents the aggregated usage incurred on that resource over the requested period. 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.
                                                  • 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.
                                                  • 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.

                                                  Use groupings to more efficiently fetch usage for large amounts of resources, such as the usage for each of your Super SIMs, if you don’t need the usage broken down by day or hour.

                                                  Example 9
                                                        
                                                        
                                                        
                                                        
                                                        Read the usage for multiple Super SIMs.

                                                        Read Grouped SIM Usage Records

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

                                                              Read Grouped Fleet Usage Records

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

                                                                    Read Grouped Network Usage Records

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

                                                                          Read Grouped Country Usage Records

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

                                                                                Read Grouped SIM Usage Records for a Country

                                                                                Read the usage for multiple Super SIMs in a single country.
                                                                                Rate this page:

                                                                                ヘルプが必要ですか?

                                                                                誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。