Skip to contentSkip to navigationSkip to topbar
Rate this Page:

Account UsageRecord Resource


(information)

Info

The Usage Records resource returns aggregated usage for all SIMs on an Account. To retrieve usage for a single SIM, use the SIM Usage Records resource.

The Usage Records list resource returns total usage information for all SIMs on an Account. Usage data is gathered over a specified period, presented as a list, aggregated according to the user-provided granularity.


_10
https://wireless.twilio.com/v1/UsageRecords


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.


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

Resource properties
account_sidtype: SID<AC>Not PII

periodtype: objectNot PII

The time period for which usage is reported. Contains start and end properties that describe the period using GMT date-time values specified in ISO 8601(link takes you to an external page) format.


commandstype: objectNot PII

An object that describes the aggregated Commands usage for all SIMs during the specified period. See Commands Usage Object(link takes you to an external page).


datatype: objectNot PII

An object that describes the aggregated Data usage for all SIMs over the 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. 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, national_roaming, and international_roaming child objects sum to the total value of the top level commands object. The same computations are done for the to_sim and from_sim parameters in the top level object.

PropertyTypeDescriptionEmpty Value
totalIntegerThe total number of Commands sent (from_sim) or received (to_sim) by all SIMs linked to the account over the given period.0
to_simIntegerThe number of Commands received by all SIMs linked to the account (to_sim) throughout the period.0
from_simIntegerThe number of Commands sent by all SIMs linked to the account (from_sim) throughout the period.0
homeObjectAn embedded Commands Usage Object that describes the number of Commands received by all SIMs linked to the account on the home network throughout the period, with keys total, to_sim and from_sim.null
national_roamingObjectAn embedded Commands Usage Object that describes the number of Commands received by all SIMs linked to the account on national roaming partner networks throughout the period, with keys total, to_sim and from_sim.null
international_roamingObjectAn embedded Commands Usage Object that describes the number of Commands received by all SIMs linked to the account 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. 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.

PropertyTypeDescriptionEmpty Value
totalIntegerThe total amount of Data consumed (downloaded and uploaded) by the SIM-connected device throughout the period.0
downloadIntegerThe amount of Data downloaded by the SIM-connected device throughout the period.0
uploadIntegerThe amount of Data uploaded by SIM-connected device throughout the period.0
unitsStringThe units in which data usage is reported for the current object. Most often 'bytes'.N/A
homeObjectAn 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_roamingObjectAn 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_roamingObjectAn 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

List all Usage Records for an Account

list-all-usage-records-for-an-account page anchor
GET https://wireless.twilio.com/v1/UsageRecords

Returns a list of Usage Records for an account.

(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
Endtype: string<DATE TIME>Not PII
Query Parameter

Only include usage that has occurred on or before this date. Format is ISO 8601(link takes you to an external page).


Starttype: string<DATE TIME>Not PII
Query Parameter

Only include usage that has occurred on or after this date. Format is ISO 8601(link takes you to an external page).


Granularitytype: enum<STRING>Not PII
Query Parameter

How to summarize the usage by time. Can be: daily, hourly, or 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.

List all Usage Records for an Account

list-all-usage-records-for-an-account-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

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

Not supported.

Not supported.

Not supported.


Rate this Page: