Skip to content Skip to navigation Skip to topbar

On this page

UsageRecord Resource

(warning)

Public Beta

Super SIM's Usage Records API is currently in Public Beta . Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Beta products are not covered by a Twilio SLA . Learn more about beta product support.

(information)

Info

To avoid ambiguity throughout this page, Sim (initial cap) refers to the Sim API resource. SIM (all caps) refers to the physical Subscriber Identity Module (that is, a SIM card) associated with a Sim resource.

A UsageRecord represents aggregated usage information over a specified period. Usage data can be filtered to show usage for a specific resource (e.g., one Super SIM or Network) or grouped around a type of resource (e.g., Sims or Networks) where one record will be returned for each resource of that type for which usage occurred during the requested period. If you want to slice up your results by UTC day or UTC hour, you can control the granularity of the results.

All dates and times are presented in UTC .

(information)

Info

The amounts in UsageRecords are presented in the period when the usage occurred, not when it was received and processed by Twilio. This is to better associate the information from this resource with real-world events.

UsageRecord Properties

Property nameTypeRequiredDescriptionChild properties

account_sidSID<AC>Optional

Not PII

The SID of the Account that incurred the usage.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

sim_sidSID<HS>Optional

Not PII

SID of a Sim resource to which the UsageRecord belongs. Value will only be present when either a value for the Sim query parameter is provided or when UsageRecords are grouped by sim. Otherwise, the value will be null.

Pattern: ^HS[0-9a-fA-F]{32}$Min length: 34Max length: 34

network_sidSID<HW>Optional

Not PII

SID of the Network resource the usage occurred on. Value will only be present when either a value for the Network query parameter is provided or when UsageRecords are grouped by network. Otherwise, the value will be null.

Pattern: ^HW[0-9a-fA-F]{32}$Min length: 34Max length: 34

fleet_sidSID<HF>Optional

Not PII

SID of the Fleet resource the usage occurred on. Value will only be present when either a value for the Fleet query parameter is provided or when UsageRecords are grouped by fleet. Otherwise, the value will be null.

Pattern: ^HF[0-9a-fA-F]{32}$Min length: 34Max length: 34

iso_countrystring<iso-country-code>Optional

Not PII

Alpha-2 ISO Country Code that the usage occurred in. Value will only be present when either a value for the IsoCountry query parameter is provided or when UsageRecords are grouped by isoCountry. Otherwise, the value will be null.

periodobjectOptional

Not PII

The time period for which the usage is reported. The period is represented as a pair of start_time and end_time timestamps specified in ISO 8601 format.

data_uploadinteger<int64>Optional

Not PII

Total data uploaded in bytes, aggregated by the query parameters.

data_downloadinteger<int64>Optional

Not PII

Total data downloaded in bytes, aggregated by the query parameters.

data_totalinteger<int64>Optional

Not PII

Total of data_upload and data_download.

data_total_billednumberOptional

Not PII

Total amount in the billed_unit that was charged for the data uploaded or downloaded. Will return 0 for usage prior to February 1, 2022. Value may be 0 despite data_total being greater than 0 if the data usage is still being processed by Twilio's billing system. Refer to Data Usage Processing for more details.

billed_unitstring<currency>Optional

Not PII

The currency in which the billed amounts are measured, specified in the 3 letter ISO 4127 format (e.g. USD, EUR, JPY). This can be null when data_toal_billed is 0 and we do not yet have billing information for the corresponding data usage. Refer to Data Usage Processing for more details.

Read UsageRecord resources

GET https://supersim.twilio.com/v1/UsageRecords

Retrieve a list of UsageRecords over a specified period aggregated according to the specified granularity.

(warning)

Warning

Usage information will be retained for 18 months , after which it will be deleted. Requests querying usage records older than 18 months will return an exception.

(information)

Info

Which resources' usage data you receive will depend on the Account SID you provide to authorize your API access. If you authorize a request using a parent Account's credentials, the call will return only usage for resources belonging to that parent Account. SIMs belonging to the parent's Subaccounts, if it has any, will not be included. To request usage information for a given Subaccount, authorize the request with that Subaccount's credentials. Only that Subaccount's resources' data will be returned.

Query parameters

Property nameTypeRequiredPIIDescription

SimstringOptional

Not PII

SID or unique name of a Sim resource. Only show UsageRecords representing usage incurred by this Super SIM.

FleetstringOptional

Not PII

SID or unique name of a Fleet resource. Only show UsageRecords representing usage for Super SIMs belonging to this Fleet resource at the time the usage occurred.

NetworkSID<HW>Optional

Not PII

SID of a Network resource. Only show UsageRecords representing usage on this network.

Pattern: ^HW[0-9a-fA-F]{32}$Min length: 34Max length: 34

IsoCountrystring<iso-country-code>Optional

Not PII

Alpha-2 ISO Country Code. Only show UsageRecords representing usage in this country.

Groupenum<string>Optional

Not PII

Dimension over which to aggregate usage records. Can be: sim, fleet, network, isoCountry. Default is to not aggregate across any of these dimensions, UsageRecords will be aggregated into the time buckets described by the Granularity parameter.

Possible values:

simfleetnetworkisoCountry

Granularityenum<string>Optional

Not PII

Time-based grouping that UsageRecords should be aggregated by. Can be: hour, day, or all. Default is all. all returns one UsageRecord that describes the usage for the entire period.

Possible values:

hourdayall

StartTimestring<date-time>Optional

Not PII

Only include usage that occurred at or after this time, specified in ISO 8601 format. Default is one month before the end_time.

EndTimestring<date-time>Optional

Not PII

Only include usage that occurred before this time (exclusive), specified in ISO 8601 format. Default is the current time.

PageSizeintegerOptional

Not PII

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

Minimum: 1Maximum: 1000

PageintegerOptional

Not PII

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

Minimum: 0

PageTokenstringOptional

Not PII

The page token. This is provided by the API.

Exclusive End Time

The end_time query parameter is exclusive . Usage that occurred before the end_time will be returned. For example to request all of the usage that occurred on February 20, 2022, you should use the following start_time and end_time request parameters:

start_time: 2022-02-20T00:00:00Z
end_time: 2022-02-21T00:00:00Z

Single SIM usage requests versus Account usage requests

Queries that are made for a single SIM by passing in a value for the Sim parameter require less computational work to aggregate the results than do requests which encompass all SIMs on your Account. Therefore queries for a single SIM may support longer ranges between the StartTime and EndTime parameters or may support queries made for any valid UTC timestamp as opposed to requiring the timestamps fall on a UTC hour or day boundary. Consequently, the sections below may be read in two ways, each depending on whether the request you are making is a Single SIM Usage Request or an Account Usage Request:

Single SIM Usage Requests — These are requests made with the Sim parameter set. They return UsageRecords representing usage only incurred by that Super SIM.
Account Usage Requests — These are requests made without any Sim parameter set. They return UsageRecords representing usage incurred by all Super SIMs in your Account.

Read filtered UsageRecords

You can filter UsageRecords to show usage for a specific resource such as a single SIM or Network.

The following query parameters will give you filtered UsageRecords:

Sim— Only show usage for the requested Sim resource. Can be passed in as either the Sim resource's Sid or UniqueName.
Fleet — Only show usage for Super SIMs that were assigned to this Fleet resource when the usage occurred. Can be passed in as either the Fleet resource's Sid or UniqueName.
Network — Only show usage on this cellular network. Only accepts the Network resource's Sid as FriendlyNames are subject to change.
IsoCountry — Only show usage incurred on cellular networks in this country. IsoCountry will be determined based on the IsoCountry of the Network resource on which the usage occurred.

When a filter is applied, the corresponding parameter on each UsageRecord will be populated with this value. For example, if you filter by a Sim resource, each UsageRecord returned will have the Sim resource's Sid in the SimSid property.

Multiple filters can be applied at once. For example, you can provide values for both Sim and Network to see the usage that a single Super SIM incurred on the requested cellular network.

Read UsageRecords over time

Each UsageRecord will represent the usage incurred over a period of time. The unit of time that each record represents depends on the Granularity query parameter. You can set the Granularity to either all, day, or hour. The default value is all.

The maximum allowed range between the StartTime and EndTime will vary depending on the Granularity you select and whether or not you are making a Single SIM Usage Request or an Account Usage Request. Further limitations on the allowed range may be imposed if you group your UsageRecords by a resource type as documented in the Group UsageRecords by resource type section below.

Single SIM usage requests

Requests for the usage incurred by a single SIM must be made using the following rules for each Granularity:

(error)

Danger

On April 25, 2024, an incident was opened due to an unannounced change in how queries made with granularity=all (or nothing provided as all is the default) are handled. If you made queries that would have been or were impacted by this change in the week up to April 25, you should have received an email notifying you about the change.

all — One record will be returned representing the usage for the entire period queried after the StartTime and EndTime are transformed, if necessary, based on the logic below. Your StartTime and EndTime request parameters can be any valid UTC timestamp. The maximum allowed query period is 18 months .
- If the period between your StartTime and EndTime is 24 hours or less, usage between the StartTime and EndTime (exclusive) you provided is returned.
- For periods over 24 hours, usage for the entirety of the first and last hour is also included in the results. The StartTime is rounded down to the start of the UTC hour. The EndTime is rounded up to the next UTC hour.
day — One record will be returned for each UTC day between the StartTime and EndTime (exclusive). Your StartTime and EndTime request parameters must fall on midnight UTC (e.g., 2021-08-19T00:00:00Z) when Granularity=day or they will be rejected. The maximum allowed query period is 3 months .
hour — One record will be returned for each UTC hour between the StartTime and EndTime (exclusive). Your StartTime and EndTime request parameters must fall on a UTC hour (e.g., 2021-08-19T03:00:00Z) when Granularity=hour or they will be rejected. The maximum allowed query period is 31 days .

Account usage requests

Requests for the usage incurred by all the Super SIMs in your Account must be made using the following rules for each Granularity:

all — One record will be returned representing the usage for the entire period between the StartTime and EndTime. Your StartTime and EndTime request parameters must fall on a UTC hour (e.g., 2021-08-19T03:00:00Z) when Granularity=all or they will be rejected. The maximum allowed query period is 18 months .
day — One record will be returned for each UTC day between the StartTime and EndTime (exclusive). Your StartTime and EndTime request parameters must fall on midnight UTC (e.g., 2021-08-19T00:00:00Z) when Granularity=day or they will be rejected. The maximum allowed query period is 3 months .
hour — One record will be returned for each UTC hour between the StartTime and EndTime (exclusive). Your StartTime and EndTime request parameters must fall on a UTC hour (e.g., 2021-08-19T03:00:00Z) when Granularity=hour or they will be rejected. The maximum allowed query period is 31 days .

(warning)

Warning

If you were a early adopter of Super SIM (<Mid 2021) and integrated with this API you may be able to make API requests on non-UTC hour or day boundaries despite the above documentation saying that you should not be allowed to. If you observe that, it is likely that your account has non-standard permissions that were enabled to ensure your applications were not disrupted when that requirement was introduced. See Legacy Functionality below for more details.

Read a UsageRecord

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    limit: 20,
13  });
14
15  usageRecords.forEach((u) => console.log(u.accountSid));
16}
17
18listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2015-05-01T20:00:00Z",
6        "end_time": "2015-06-01T20:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": null,
15      "fleet_sid": null,
16      "network_sid": null,
17      "iso_country": null
18    }
19  ],
20  "meta": {
21    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?PageSize=50&Page=0",
22    "key": "usage_records",
23    "next_page_url": null,
24    "page": 0,
25    "page_size": 50,
26    "previous_page_url": null,
27    "url": "https://supersim.twilio.com/v1/UsageRecords?PageSize=50&Page=0"
28  }
29}

Read daily UsageRecords

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    granularity: "day",
13    limit: 20,
14  });
15
16  usageRecords.forEach((u) => console.log(u.accountSid));
17}
18
19listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": null,
15      "fleet_sid": null,
16      "network_sid": null,
17      "iso_country": null
18    },
19    {
20      "period": {
21        "start_time": "2019-05-02T00:00:00Z",
22        "end_time": "2019-05-03T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": null,
31      "fleet_sid": null,
32      "network_sid": null,
33      "iso_country": null
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?Granularity=day&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?Granularity=day&PageSize=50&Page=0"
44  }
45}

Read hourly UsageRecords

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    granularity: "hour",
13    limit: 20,
14  });
15
16  usageRecords.forEach((u) => console.log(u.accountSid));
17}
18
19listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-01T01:00:00Z",
6        "end_time": "2019-05-01T02:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": null,
15      "fleet_sid": null,
16      "network_sid": null,
17      "iso_country": null
18    },
19    {
20      "period": {
21        "start_time": "2019-05-01T00:00:00Z",
22        "end_time": "2019-05-01T01:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": null,
31      "fleet_sid": null,
32      "network_sid": null,
33      "iso_country": null
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?Granularity=hour&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?Granularity=hour&PageSize=50&Page=0"
44  }
45}

Read daily UsageRecords for a SIM

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    granularity: "day",
13    sim: "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14    limit: 20,
15  });
16
17  usageRecords.forEach((u) => console.log(u.accountSid));
18}
19
20listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
10      "data_upload": 150000,
11      "data_download": 150000,
12      "data_total": 300000,
13      "data_total_billed": "0.03",
14      "billed_unit": "USD",
15      "fleet_sid": null,
16      "network_sid": null,
17      "iso_country": null
18    },
19    {
20      "period": {
21        "start_time": "2019-05-02T00:00:00Z",
22        "end_time": "2019-05-03T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
31      "fleet_sid": null,
32      "network_sid": null,
33      "iso_country": null
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&Granularity=day&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&Granularity=day&PageSize=50&Page=0"
44  }
45}

Read daily UsageRecords for a Fleet

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    fleet: "HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13    granularity: "day",
14    limit: 20,
15  });
16
17  usageRecords.forEach((u) => console.log(u.fleetSid));
18}
19
20listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": null,
15      "fleet_sid": "HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "network_sid": null,
17      "iso_country": null
18    },
19    {
20      "period": {
21        "start_time": "2019-05-02T00:00:00Z",
22        "end_time": "2019-05-03T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": null,
31      "fleet_sid": "HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
32      "network_sid": null,
33      "iso_country": null
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?Fleet=HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&Granularity=day&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?Fleet=HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&Granularity=day&PageSize=50&Page=0"
44  }
45}

Read daily UsageRecords for a Network

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    granularity: "day",
13    network: "HWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14    limit: 20,
15  });
16
17  usageRecords.forEach((u) => console.log(u.networkSid));
18}
19
20listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": null,
15      "fleet_sid": null,
16      "network_sid": "HWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17      "iso_country": null
18    },
19    {
20      "period": {
21        "start_time": "2019-05-03T00:00:00Z",
22        "end_time": "2019-05-04T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": null,
31      "fleet_sid": null,
32      "network_sid": "HWbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
33      "iso_country": null
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?Group=network&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?Group=network&PageSize=50&Page=0"
44  }
45}

Read daily UsageRecords for a country

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    granularity: "day",
13    isoCountry: "FR",
14    limit: 20,
15  });
16
17  usageRecords.forEach((u) => console.log(u.isoCountry));
18}
19
20listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": null,
15      "fleet_sid": null,
16      "network_sid": null,
17      "iso_country": "FR"
18    },
19    {
20      "period": {
21        "start_time": "2019-05-02T00:00:00Z",
22        "end_time": "2019-05-03T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": null,
31      "fleet_sid": null,
32      "network_sid": null,
33      "iso_country": "FR"
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?IsoCountry=FR&Granularity=day&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?IsoCountry=FR&Granularity=day&PageSize=50&Page=0"
44  }
45}

Group UsageRecords by resource type

You can group UsageRecords around a type of resource (e.g., Sims or Networks). Each UsageRecord represents the aggregated usage incurred by an instance of the resource (e.g. a Sim or a Network) over a period of time.

(warning)

Warning

Grouping your UsageRecords by SIM or by Fleet is currently in Private Beta . To request access to this functionality, contact your Twilio Account Executive.

You can group your UsageRecords by the following resource types:

sim — Group usage by Super SIM. Each UsageRecord represents the usage incurred by a Sim resource over the UsageRecord's period. When grouping usage by Super SIM, the maximum allowed query period between the StartTime and EndTime is 31 days for all Granularity values. This functionality is in Private Beta and you may need it unlocked on your Twilio Account.
fleet — Group usage by Fleet. Each UsageRecord represents the usage incurred by all the Super SIMs assigned to a Fleet resource when the usage occurred over the UsageRecord's period. This functionality is in Private Beta and you may need it unlocked on your Twilio Account.
network — Group usage by Network. Each UsageRecord represents the usage incurred on a Network resource over the UsageRecord's period.
isoCountry — Group usage by country. Each UsageRecord represents the usage incurred on all of the Network resources in a country over the UsageRecord's period.

When a grouping is applied, the corresponding resource type's parameter on each UsageRecord will be populated with its identifier. For example, if you group by sim, each UsageRecord returned will have the Sim resource's Sid in the SimSid property.

You can filter grouped UsageRecords.

Data Usage Processing

Usage events containing how much data your SIMs used are simultaneously handed off to the aggregation engine that powers the UsageRecords API and Twilio's billing system. As a result, for each event handled, the usage in bytes will be reflected in the results from the UsageRecords API before the amount charged will be. Once the usage event has been processed by our billing system and the output billing event is received by the aggregation engine, it too will be reflected in the results via the data_total_billed property. All data billing events should be received and reflected in your results within 24 hours from when the usage occurred.

(information)

Info

When generating critical spending reports, such as those you may need for monthly reporting for your business' operations, using this API, we recommend you wait at least 24 hours after the reported period ends to generate the report to allow usage events to be processed, charged, and reflected in your results.

Read grouped SIM UsageRecords

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    group: "sim",
13    limit: 20,
14  });
15
16  usageRecords.forEach((u) => console.log(u.simSid));
17}
18
19listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "fleet_sid": null,
16      "network_sid": null,
17      "iso_country": null
18    },
19    {
20      "period": {
21        "start_time": "2019-05-03T00:00:00Z",
22        "end_time": "2019-05-04T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": "HSbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
31      "fleet_sid": null,
32      "network_sid": null,
33      "iso_country": null
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?Group=sim&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?Group=sim&PageSize=50&Page=0"
44  }
45}

Read grouped Fleet UsageRecords

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    group: "fleet",
13    limit: 20,
14  });
15
16  usageRecords.forEach((u) => console.log(u.fleetSid));
17}
18
19listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": null,
15      "fleet_sid": "HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "network_sid": null,
17      "iso_country": null
18    },
19    {
20      "period": {
21        "start_time": "2019-05-03T00:00:00Z",
22        "end_time": "2019-05-04T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": null,
31      "fleet_sid": "HFbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
32      "network_sid": null,
33      "iso_country": null
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?Group=fleet&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?Group=fleet&PageSize=50&Page=0"
44  }
45}

Read grouped Network UsageRecords

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    group: "network",
13    limit: 20,
14  });
15
16  usageRecords.forEach((u) => console.log(u.networkSid));
17}
18
19listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": null,
15      "fleet_sid": null,
16      "network_sid": "HWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17      "iso_country": null
18    },
19    {
20      "period": {
21        "start_time": "2019-05-03T00:00:00Z",
22        "end_time": "2019-05-04T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": null,
31      "fleet_sid": null,
32      "network_sid": "HWbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
33      "iso_country": null
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?Group=network&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?Group=network&PageSize=50&Page=0"
44  }
45}

Read grouped country UsageRecords

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    group: "isoCountry",
13    limit: 20,
14  });
15
16  usageRecords.forEach((u) => console.log(u.isoCountry));
17}
18
19listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": null,
15      "fleet_sid": null,
16      "network_sid": null,
17      "iso_country": "FR"
18    },
19    {
20      "period": {
21        "start_time": "2019-05-03T00:00:00Z",
22        "end_time": "2019-05-04T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": null,
31      "fleet_sid": null,
32      "network_sid": null,
33      "iso_country": "US"
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?Group=isoCountry&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?Group=isoCountry&PageSize=50&Page=0"
44  }
45}

Read grouped SIM UsageRecords for a country

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUsageRecord() {
11  const usageRecords = await client.supersim.v1.usageRecords.list({
12    group: "sim",
13    limit: 20,
14  });
15
16  usageRecords.forEach((u) => console.log(u.simSid));
17}
18
19listUsageRecord();

Output

1{
2  "usage_records": [
3    {
4      "period": {
5        "start_time": "2019-05-03T00:00:00Z",
6        "end_time": "2019-05-04T00:00:00Z"
7      },
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "data_upload": 150000,
10      "data_download": 150000,
11      "data_total": 300000,
12      "data_total_billed": "0.03",
13      "billed_unit": "USD",
14      "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "fleet_sid": null,
16      "network_sid": null,
17      "iso_country": "FR"
18    },
19    {
20      "period": {
21        "start_time": "2019-05-03T00:00:00Z",
22        "end_time": "2019-05-04T00:00:00Z"
23      },
24      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "data_upload": 150000,
26      "data_download": 150000,
27      "data_total": 300000,
28      "data_total_billed": "0.03",
29      "billed_unit": "USD",
30      "sim_sid": "HSbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
31      "fleet_sid": null,
32      "network_sid": null,
33      "iso_country": "FR"
34    }
35  ],
36  "meta": {
37    "first_page_url": "https://supersim.twilio.com/v1/UsageRecords?IsoCountry=FR&Group=sim&PageSize=50&Page=0",
38    "key": "usage_records",
39    "next_page_url": null,
40    "page": 0,
41    "page_size": 50,
42    "previous_page_url": null,
43    "url": "https://supersim.twilio.com/v1/UsageRecords?IsoCountry=FR&Group=sim&PageSize=50&Page=0"
44  }
45}

Legacy Functionality

If you were an early user of this API and integrated into your application before it was publicly released, you may experience some slightly different behavior explained below due to having flags added to your account to ensure that your application was not disrupted by changing the expected response from the API when it was released.

Querying Account Usage With Non-UTC Hour or UTC Day Boundaries

If your account was identified as using this API before we implemented requirements that the StartTime and EndTime request parameters must fall on UTC day or hour boundaries depending on whether you were making a Single SIM Usage Request or an Account Usage Request and what Granularity was used, a flag was added to your account to continue to returning with a 200 response instead of throwing an exception to avoid disrupting your application. While we accepted your request, the timestamps used to request data from our systems was transformed as described below. In the future you may be contacted by our team asking you to adjust your application to ensure that data returned matches your request parameters and these unique account permissions can be removed.

Granularity hour and day

Your StartTime and EndTime values will be effectively rounded up to the next UTC hour or UTC day if the values provided do not fall on a UTC hour or UTC day boundary, respectively. For example, a request made with Granularity=day with StartTime=``2021-07-01T00:30:00Z (July 1, 2021 12:30am UTC) and EndTime=``2021-07-15T14:00:00Z (July 15, 2021 2:00pm UTC) will return results from the start of July 2nd through the end of July 15th . Similarly, a request made with Granularity=hour with StartTime=``2021-07-01T00:30:00Z (12:30am UTC) and EndTime=``2021-07-01T10:30:00Z (10:30am UTC) will return results for 1:00am UTC to 11:00am UTC .

To ensure that you receive the expected results, it is recommended that you make all requests with Granularity=hour with StartTime and EndTime values that fall on a UTC hour boundary (e.g., StartTime=2021-07-01T00:00:00Z) and all requests with Granularity=day with StartTime and EndTime values that fall on midnight UTC (e.g., EndTime=2021-07-16T00:00:00Z).

Granularity all

For Account Usage requests made with Granularity=all, if your StartTime and EndTime parameters are less than one hour apart, the results of all raw usage records where the measured period started between the StartTime and the EndTime will be aggregated. If your StartTime and EndTime parameters are more than one hour apart, then both the StartTime and EndTime parameters will be rounded up to the nearest UTC hour as described in the section above for Granularity=hour.

To ensure that you receive expected results, you should make all Account Usage requests with StartTime and EndTime values that fall on a UTC hour boundary.

Single SIM Usage Requests made with Granularity=all will correctly return the usage that occurred between any StartTime and EndTime up to the allowed range. This is a result of how these requests are processed — see Single SIM Usage Requests versus Account Usage Requests for details.