Menu

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?

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.

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.

Sim UsageRecords properties

Names in PHP format
simSid
sid_like<DE> Not PII

The SID of the Sim resource that this Usage Record is for.

accountSid
sid<AC> Not PII

The SID of the Account that created the UsageRecord resource.

period
object Not PII

The time period for which the usage is reported. Contains start and end datetime values given as GMT in ISO 8601 format.

commands
object Not PII

An object that describes the SIM's usage of Commands during the specified period. See Commands Usage Object.

data
object Not PII

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

get
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.

Parameters
Names in None format
sim_sid
Required
get sid_like<DE> Not PII

The SID of the Sim resource to read the usage from.

end
Optional
get date_time<iso8601> Not PII

Only include usage that occurred on or before this date, specified in ISO 8601. The default is the current time.

start
Optional
get date_time<iso8601> Not PII

Only include usage that has occurred on or after this date, specified in ISO 8601. The default is one month before the end parameter value.

granularity
Optional
get enum:granularity Not PII

How to summarize the usage by time. Can be: daily, hourly, or all. The default is all. A value of all returns one Usage Record that describes the usage for the entire period.

Example 1
        
        
        
        
        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 browsing the Twilio tag on Stack Overflow.