Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

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.


_10
https://wireless.twilio.com/v1/Sims/{SIM_SID}/UsageRecords

(information)

Info

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-availability page anchor

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.


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

sim-usagerecords-properties page anchor
Resource properties
sim_sidtype: stringNot PII

account_sidtype: SID<AC>Not PII

The SID of the Account(link takes you to an external page) that created the UsageRecord resource.


periodtype: objectNot PII

The time period for which the usage is reported. Contains start and end datetime values given as GMT in ISO 8601(link takes you to an external page) format.


commandstype: objectNot PII

An object that describes the SIM's usage of Commands during the specified period. See Commands Usage Object(link takes you to an external page).


datatype: objectNot PII

An object that describes the SIM's data usage during the specified period. See Data Usage Object(link takes you to an external page).

Commands Usage Object

commands-usage-object page anchor

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 TypeDescriptionEmpty Value
total IntegerThe total number of Commands sent (from_sim) or received (to_sim) by the SIM over the given period.0
to_sim IntegerThe number of Commands received by the SIM (to_sim) throughout the period.0
from_sim IntegerThe number of Commands sent by the SIM (from_sim) throughout the period.0
home ObjectAn 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 ObjectAn 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 ArrayAn 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.[]

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 TypeDescriptionEmpty Value
total IntegerThe total amount of Data consumed (downloaded and uploaded) by the SIM-connected device throughout the period.0
download IntegerThe amount of Data downloaded by the SIM-connected device throughout the period.0
upload IntegerThe amount of Data uploaded by SIM-connected device throughout the period.0
units StringThe units in which data usage is reported for the current object. Most often 'bytes'.N/A
home ObjectAn 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 ObjectAn 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 ArrayAn 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

read-multiple-usagerecord-resources page anchor
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.

(error)

Danger

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

list-parameters page anchor
URI parameters
SimSidtype: stringNot PII
Path Parameter

The SID of the Sim resource(link takes you to an external page) to read the usage from.


Endtype: string<DATE TIME>Not PII
Query Parameter

Only include usage that occurred on or before this date, specified in ISO 8601(link takes you to an external page). The default is the current time.


Starttype: string<DATE TIME>Not PII
Query Parameter

Only include usage that has occurred on or after this date, specified in ISO 8601(link takes you to an external page). The default is one month before the end parameter value.


Granularitytype: enum<STRING>Not PII
Query Parameter

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.

Possible values:
hourlydailyall

PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Read multiple Sim Usage Record resources

read-multiple-sim-usage-record-resources page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.wireless.v1.sims('DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.usageRecords
_11
.list({limit: 20})
_11
.then(usageRecords => usageRecords.forEach(u => console.log(u.simSid)));

Output

_75
{
_75
"usage_records": [
_75
{
_75
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_75
"commands": {
_75
"billing_units": "USD",
_75
"billed": 0,
_75
"total": 3,
_75
"from_sim": 1,
_75
"to_sim": 2,
_75
"home": {
_75
"billing_units": "USD",
_75
"billed": 0,
_75
"total": 3,
_75
"from_sim": 1,
_75
"to_sim": 2
_75
},
_75
"national_roaming": {
_75
"billing_units": "USD",
_75
"billed": 0,
_75
"total": 0,
_75
"from_sim": 0,
_75
"to_sim": 0
_75
},
_75
"international_roaming": []
_75
},
_75
"data": {
_75
"billing_units": "USD",
_75
"billed": 0.35,
_75
"total": 3494609,
_75
"upload": 731560,
_75
"download": 2763049,
_75
"units": "bytes",
_75
"home": {
_75
"billing_units": "USD",
_75
"billed": 0.35,
_75
"total": 3494609,
_75
"upload": 731560,
_75
"download": 2763049,
_75
"units": "bytes"
_75
},
_75
"national_roaming": {
_75
"billing_units": "USD",
_75
"billed": 0,
_75
"total": 0,
_75
"upload": 0,
_75
"download": 0,
_75
"units": "bytes"
_75
},
_75
"international_roaming": []
_75
},
_75
"sim_sid": "DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_75
"period": {
_75
"start": "2015-07-30T20:00:00Z",
_75
"end": "2015-07-30T20:00:00Z"
_75
}
_75
},
_75
{
_75
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_75
"commands": {},
_75
"data": {},
_75
"sim_sid": "DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_75
"period": {}
_75
}
_75
],
_75
"meta": {
_75
"first_page_url": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/UsageRecords?Start=2015-07-30T20%3A00%3A00Z&End=2015-07-30T20%3A00%3A00Z&PageSize=50&Page=0",
_75
"key": "usage_records",
_75
"next_page_url": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/UsageRecords?Start=2015-07-30T20%3A00%3A00Z&End=2015-07-30T20%3A00%3A00Z&PageSize=50&Page=1",
_75
"page": 0,
_75
"page_size": 50,
_75
"previous_page_url": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/UsageRecords?Start=2015-07-30T20%3A00%3A00Z&End=2015-07-30T20%3A00%3A00Z&PageSize=50&Page=0",
_75
"url": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/UsageRecords?Start=2015-07-30T20%3A00%3A00Z&End=2015-07-30T20%3A00%3A00Z&PageSize=50&Page=0"
_75
}
_75
}


Rate this page: