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 (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 UsageRecords are not grouped by a resource type, each record will represent a period of time (e.g., 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
|
The SID of the Account that incurred the usage. |
sim_sid
|
SID of a Sim resource to which the UsageRecord belongs. Value will only be present when either a value for the |
network_sid
|
SID of the Network resource the usage occurred on. Value will only be present when either a value for the |
fleet_sid
|
SID of the Fleet resource the usage occurred on. Value will only be present when either a value for the |
iso_country
|
Alpha-2 ISO Country Code that the usage occurred in. Value will only be present when either a value for the |
period
|
The time period for which the usage is reported. The period is represented as a pair of |
data_upload
|
Total data uploaded in bytes, aggregated by the query parameters. |
data_download
|
Total data downloaded in bytes, aggregated by the query parameters. |
data_total
|
Total of data_upload and data_download. |
Read UsageRecord resources
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
|
SID or unique name of a Sim resource. Only show UsageRecords representing usage incurred by this Super SIM. |
fleet
Optional
|
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
|
SID of a Network resource. Only show UsageRecords representing usage on this network. |
iso_country
Optional
|
Alpha-2 ISO Country Code. Only show UsageRecords representing usage in this country. |
group
Optional
|
Dimension over which to aggregate usage records. Can be: |
granularity
Optional
|
Time-based grouping that UsageRecords should be aggregated by. Can be: |
start_time
Optional
|
Only include usage that occurred at or after this time, specified in ISO 8601 format. Default is one month before the |
end_time
Optional
|
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 record 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 theStartTimeandEndTime. The maximum allowed query period is 18 months.day— One record will be returned for each UTC day betweenStartTimeandEndTime. Each record will start inclusively and end exclusively at midnight UTC. The maximum allowed query period is three months.hour— One record will be returned for each UTC hour betweenStartTimeandEndTime. The maximum allowed query period is 31 days.
Example 1
Example 2
Example 3
Read filtered UsageRecords
You can filter UsageRecordresources to show usage for a specific resource such as a single Sim resource or 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’sSidorUniqueName.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’sSidorUniqueName.Network— Only show usage on this cellular network. Only accepts the Network resource’sSidasFriendlyNamesare subject to change.IsoCountry— Only show usage incurred on cellular networks in this country.IsoCountrywill be determined based on theIsoCountryof 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.
Example 4
Example 5
Example 6
Example 7
Example 8
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 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. When grouping usage by Super Sim, the maximum allowed query period is 31 days.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.
If you don’t need the usage broken down by day or hour, use groupings to fetch usage more efficiently when requesting large numbers of resources, such as the usage for each of your Super SIMs.
Example 9
Example 10
Example 11
Example 12
Example 13
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.