Menu

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?

REST API: SIM Usage Records

The SIM Usage Records list resource returns usage information for a SIM over a specified period, presented as a list, aggregated according to the user-provided granularity.

HTTP Resources and Methods

SIM Usage List Resource

Resource URLs

https://wireless.twilio.com/v1/Sims/{SimSid}/UsageRecords
https://wireless.twilio.com/v1/Sims/{SimUniqueName}/UsageRecords

Resource Properties

This resource and its subresources always return a list of SIM Usage Records. Each Usage Record is represented by the following properties:

Names in PHP format
simSid
sid_like<DE> Not PII

The unique id of the SIM resource that this Usage Record is for.

accountSid
sid<AC> Not PII

The unique id of the Account that the SIM belongs to.

period
object Not PII

The time period for which usage is reported. Contains start and end properties representing a start and end date given as GMT in ISO 8601 format.

commands
object Not PII

An object representing the Commands usage for the SIM over the period. See Commands Usage Object below.

data
object Not PII

An object representing the Data usage for the SIM over the period. See Data Usage Object below.

Commands Usage Object

The Commands usage object reports usage of Commands for the period. Usage detail is provided along three dimensions: Total, Home, and National Roaming.

The Commands Usage object is presented as a tree-like structure. For example, the total value from the home child object and the national_roaming child 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 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 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
Data Usage Object

The Data usage object reports usage of Data for the period. Usage detail is provided along three dimensions: Total, Home, and National Roaming.

The Data Usage object is presented as a tree-like structure. For example, the total value from the home child object and the national_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 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 Object An embedded Data Usage Object 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. null

SIM Usage Records List Resource

HTTP GET

Returns Usage Records for the SIM identified by its Sid or Unique Name.

Period Filter

By default, the SIM Usage Records list resource will return Usage Records for the past month. In order to retrieve usage for a different time period, use the following parameters:

Parameter Description Default
End Only include usage that has occurred on or before this date. Format is ISO 8601. Now
Start Only include usage that has occurred on or after this date. Format is ISO 8601. One month before End
Other List Filters

The following GET query string parameters allow you to modify the list returned. Note, parameters are case-sensitive:

Parameter Description Default
Granularity The time-based grouping that results are aggregated by. Valid values are daily, hourly, all. all will return one Usage Record for the entire period. all
List Filters

The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

Parameter Description
Sim Only return Commands to or from this SIM.
Status Only return Commands with this status value.
Direction Only return Commands with this direction value.
Example

Request a list of daily SIM Usage Records for the last month using the SIM Sid, represented as JSON.

        
        
        
        

        HTTP POST

        Not supported.

        HTTP PUT

        Not supported.

        HTTP DELETE

        Not supported.

        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.