Sim UsageRecord Resource
The Sim UsageRecords list resource returns usage information for a SIM over a specified period, presented as a list, and aggregated according to the user-provided granularity.
https://wireless.twilio.com/v1/Sims/{SIM_SID}/UsageRecords
The SIM Usage Records resource returns usage for a single SIM. To retrieve aggregated usage for all SIMs on an Account, use the Usage Records resource.
Data availability
Data records used to charge your account and populate this resource are not delivered in real time and can be delayed due to both regular and unplanned maintenance at our carrier partners. Usage may not be reflected from this resource for up to 24 hours from when it occurred. All usage will typically be processed within 48 hours from when it occurred.
Retention period
Usage information will be retained for 18 months, after which it will be deleted. Querying usage records more than 18 months old can result in incomplete data.
Sim UsageRecords properties
Resource Properties in REST API format | |
---|---|
sim_sid
|
The SID of the Sim resource that this Usage Record is for. |
account_sid
|
The SID of the Account that created the UsageRecord resource. |
period
|
The time period for which the usage is reported. Contains |
commands
|
An object that describes the SIM's usage of Commands during the specified period. See Commands Usage Object. |
data
|
An object that describes the SIM's data usage during the specified period. See Data Usage Object. |
Commands Usage Object
The Commands usage object reports usage of Commands for the period.
The Commands Usage object is presented as a tree-like structure. For example, the total
value from the home
child object, the national_roaming
child object , and the international_roaming
object sum to the total
value of the top level commands
object. This is the same for the to_sim
and from_sim
parameters.
Property Data Type |
Description | Empty Value |
---|---|---|
total Integer |
The total number of Commands sent (from_sim ) or received (to_sim ) by the SIM over the given period. |
0 |
to_sim Integer |
The number of Commands received by the SIM (to_sim ) throughout the period. |
0 |
from_sim Integer |
The number of Commands sent by the SIM (from_sim ) throughout the period. |
0 |
home Object |
An embedded Commands Usage Object that describes the number of Commands received by the SIM on the home network throughout the period, with keys total , to_sim and from_sim . |
null |
national_roaming Object |
An embedded Commands Usage Object that describes the number of Commands received by the SIM on national roaming partner networks throughout the period, with keys total , to_sim and from_sim . |
null |
international_roaming Array |
An array of Commands Usage Objects, one for each country with usage, that describes the number of Commands received by or sent from the SIM on international roaming partner networks throughout the period, with keys total , to_sim and from_sim . |
[] |
Data Usage Object
The Data usage object reports usage of Data for the period.
The Data Usage object is presented as a tree-like structure. For example, the total
value from the home
child object, the national_roaming
child object, and the international_roaming
child object sum to the total
value of the top level data
object. This is the same for the download
and upload
parameters.
Property Data Type |
Description | Empty Value |
---|---|---|
total Integer |
The total amount of Data consumed (downloaded and uploaded) by the SIM-connected device throughout the period. | 0 |
download Integer |
The amount of Data downloaded by the SIM-connected device throughout the period. | 0 |
upload Integer |
The amount of Data uploaded by SIM-connected device throughout the period. | 0 |
units String |
The units in which data usage is reported for the current object. Most often 'bytes'. | N/A |
home Object |
An embedded Data Usage Object that describes the amount of Data consumed by the SIM-connected device on the home network throughout the period, with keys total , download , upload and units . |
null |
national_roaming Object |
An embedded Data Usage Object that describes the amount of Data consumed by the SIM-connected device on national roaming partner networks throughout the period, with keys total , download , upload and units . |
null |
international_roaming Array |
An array of Data Usage Objects, one for each country with usage, that describes the amount of Data consumed by the SIM-connected device on international roaming partner networks throughout the period, with keys total , download , upload and units . |
[] |
Read multiple UsageRecord resources
https://wireless.twilio.com/v1/Sims/{SimSid}/UsageRecords
The {SimSid}
parameter can be the SID or the UniqueName
of the Sim resource to collect usage data about.
Usage information will be retained for 18 months, after which it will be deleted. Querying usage records older than 18 months can result in incomplete data.
Parameters
Parameters in REST API format | |
---|---|
sim_sid
Path
|
The SID of the Sim resource to read the usage from. |
end
Optional
|
Only include usage that occurred on or before this date, specified in ISO 8601. The default is the current time. |
start
Optional
|
Only include usage that has occurred on or after this date, specified in ISO 8601. The default is one month before the |
granularity
Optional
|
How to summarize the usage by time. Can be: |
Example 1
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.