Skip to content Skip to navigation Skip to topbar

On this page

UsageRecords Resource

(warning)

Public Beta

The Super SIM's UsageRecords API might have some unimplemented features or others that might change before Twilio declares it Generally Available. Twilio SLAs don't cover Beta products. To learn more, consult beta product support.

A UsageRecords response represents the aggregated usage data incurred over a specified period of time. With this API call, you can filter or group usage by resource and slice the results by increments of time.

(information)

Sim vs. SIM

Sim, in initial caps, refers to the Sim API resource.
SIM, in all caps, refers to the physical or virtual Subscriber Identity Module (SIM) card, associated with a Sim resource.

Data considerations

This resource requests return data for when the usage occurred, not when Twilio received and processed the request.
This resource returns all dates and times in UTC.
Twilio retains usage information for 18 months then deletes it. Requests for usage records older than 18 months return an exception.
Resource usage data you receive depends on the Account SID that authorized your API access.
- To request data for a parent Account, authorize the request with that account's credentials. After authorization, API calls only return usage data for SIMs belonging to that parent Account. It omits SIMs belonging to the parent's Subaccounts, if any.
- To request data for a given Subaccount, authorize the request with that Subaccount's credentials. After authorization, API calls only return that Subaccount's resources' data.

Process data usage

Twilio sends usage events to the aggregation engine that powers the UsageRecords API and Twilio's billing system. These events include how much data your SIMs used.

Twilio sends usage data to the UsageRecords aggregation engine and Twilio's billing system at the same time. This results in UsageRecords displaying the current data usage, but not the current amount billed. Within 24 hours of usage event occurring, the billing system processes your data usage then returns the cost data to the aggregation engine. The UsageRecords call then reflects the current costs in its data_total_billed property.

If you use this API to generate critical spending reports, wait at least 24 hours after the reported period ends. This allows time to process and charge usage events so your results reflect that billing.

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.

periodobject

Optional

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_billednumber

Optional

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.

Return UsageRecords entries

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

Return a list of UsageRecords entries. These entries cover a specified period and aggregated to a specified granularity.

Query parameters

Property nameTypeRequiredPIIDescription

Simstring

Optional

Not PII

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

Fleetstring

Optional

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.

PageSizeinteger

Optional

Not PII

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

Not PII

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

Minimum: 0

PageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Exclusive end time

The end_time query parameter is exclusive. This means a response to this API call excludes any usage records that occur on or after its date and time.

Example: Request all usage on single date

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

As Twilio excludes usage from end_time and later, the response omits any usage that occurred at midnight on February 21, 2022.

Single SIM usage requests versus Account usage requests

You can request usage data for a single SIM or for all SIMs in your account.

Queries for a single SIM require less compute time than queries for all SIMs on your account. Single SIM queries may have fewer limits for this reason.

They may support longer ranges between the StartTime and EndTime parameters.
They may support queries made for any valid Coordinated Universal Time (UTC) timestamp and not require that the timestamps fall on a UTC hour or day boundary.

When applicable, the following sections include both a Single SIM Usage Request and an Account Usage Request. To query one Super SIM, set a value for the Sim request parameter.

Return all UsageRecords

This example returns the aggregated usage data for the account. The response is neither filtered or grouped.

Return all 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    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}

Filter `UsageRecords` response entries

To filter usage data to a specific resource type, add parameters to your UsageRecords requests. To filter your UsageRecords request, include one or more of the following request parameters:

Parameter	Limits response to records	Allowed value
`Sim`	Requested Sim resource	Sim resource's `Sid` or `UniqueName`
`Fleet`	Super SIMs assigned to this Fleet resource	Fleet resource's `Sid` or `UniqueName`
`Network`	This cellular network	Network resource's `Sid`
`IsoCountry`	Cellular networks in this country	`IsoCountry` of the Network resource

When you set a filtering parameter, the UsageRecords entry returns this value in its corresponding property.

Return daily UsageRecords for one SIM

If your request includes a Sim name-value pair, the UsageRecords response returns an entry for one Super SIM. Set the value of the Super SIM in the Sim parameter. The response returns this parameter in the value of its sim_sid property.

This example returns the aggregated usage data for the Super SIM specified in the Sim parameter displayed in its sim_sid property. In the following example, that value equals HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.

Return 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}

Return daily UsageRecords for one Fleet

If your request includes a Fleet name-value pair, the UsageRecords response returns an entry for one fleet of Super SIMs. Set the value of the fleet in the Fleet parameter. The response returns this parameter in the value of its fleet_sid property.

This example returns the aggregated usage data for the group of Super SIMs specified in the Fleet parameter displayed in its fleet_sid property. In the following example, that value equals HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.

Return 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}

Return daily UsageRecords for one Network

If your request includes a Network name-value pair, the UsageRecords response returns an entry for one carrier network. Set the value of the carrier network in the Network parameter. The response returns this parameter in the value of its network_sid property.

This example returns the aggregated usage data for the carrier network specified in the Network parameter displayed in its network_sid property. In the following example, that value equals HWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.

Return 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}

Return daily UsageRecords for one country

If your request includes a IsoCountry name-value pair, the UsageRecords response returns an entry for one carrier network. Set the value of the carrier network in the IsoCountry parameter. The response returns this parameter in the value of its iso_country property.

This example returns the aggregated usage data for the carrier network specified in the IsoCountry parameter displayed in its iso_country property. In the following example, that value equals FR (for France).

Return daily UsageRecords for one 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}

Return daily UsageRecords for one SIM on one Network

You can apply multiple filters to one request. To see the usage that a single Super SIM incurred on the requested cellular network, provide values for both Sim and Network.

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

Limit `UsageRecords` to one period of time

Each UsageRecords request returns the usage incurred over a period of time. The period of time covers a range within the following limits:

It includes the StartTime but omits the EndTime as noted previously.
It depends on the value of the Granularity parameter. The Granularity accepts all, day, or hour and defaults to all.
The maximum period depends on the values you passed to Granularity and Sim.
If you group your UsageRecords by a resource type, the range might be further limited.

Single SIM requestAccount request

For a single SIM's usage, the Granularity parameter applies the following limits based on its value.

Value	Returns One Record for	Accepted UTC timestamps	Maximum Query Period
`all`	The entire period*	Any valid UTC timestamp	18 months
`day`	Each UTC day	Midnight for any day at UTC	3 months
`hour`	Each UTC hour	Top of any hour at UTC	31 days

* For periods over 24 hours, UsageRecords calls using Granularity of all include usage for the entire first and last hour. It rounds StartTime down to the start of the UTC hour and EndTime up to the next UTC hour.

Return one Super SIM's daily UsageRecords

Return daily UsageRecords for one Super 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}

For the usage of all the Super SIMs in your Account, the Granularity parameter applies the following limits based on its value.

Value	Returns One Entry for	Accepted UTC timestamps	Maximum Query Period
`all`	The entire period	Any valid UTC timestamp	18 months
`day`	Each UTC day	Midnight for any day at UTC	3 months
`hour`	Each UTC hour	Top of any hour at UTC	31 days

Return all 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}

Return 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}

(warning)

Warning

If you can make API requests on non-UTC hour or day boundaries, your account might have non-standard permissions enabled. To learn more, consult Legacy Functionality.

Group UsageRecords by resource type

You can group UsageRecords entries around a type of resource. Resource types include SIM, Fleet, Network, and Country. Each UsageRecords entry represents how much the account used the chosen record type over a period of time. Each UsageRecords entry returns data aggregated for each type of resource.

(warning)

Private Beta

To group your UsageRecords entries by SIM or by Fleet, you must join a Private Beta. To join, contact your Twilio Account Executive.

To group your UsageRecords entries, set Group to one of the following values:

Value	Groups by	Covers usage for	Availability	Notes
`sim`	Super SIM	one Super SIM	Private Beta	maximum query period 31 days
`fleet`	Fleet	all Super SIMs assigned to one Fleet	Private Beta
`network`	Network	one Network	GA
`isoCountry`	Country	all Networks in one country	GA

When you set a Group, the response includes the resource type's parameter on each UsageRecords entry to the Group value.

You can filter grouped UsageRecords.

Return UsageRecords grouped by SIM

When your request sets a Group to sim, the UsageRecords response returns an entry for each Super SIM. The response returns each Super SIM value in its sim_sid property.

This example returns the aggregated usage data for each Super SIM displayed in its sim_sid property. In the following example, that value covers HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa and HSbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.

Return 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}

Return UsageRecords grouped by Fleet

When your request sets a Group to fleet, the UsageRecords response returns an entry for each group of Super SIMs identified as a Fleet. The response returns each Fleet value in its fleet_sid property.

This example returns the aggregated usage data for each Super SIM displayed in its fleet_sid property. In the following example, that value covers HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa and HFbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.

When your request sets a Group to fleet, the fleet_sid property of each UsageRecords entry returned includes a unique value for the fleet_sid.

Return 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}

Return UsageRecords grouped by Network

When your request sets a Group to network, the network_sid property of each UsageRecords entry returned includes a unique value for network_sid.

Return 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}

Return UsageRecords grouped by country

Return 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}

Return UsageRecords grouped by SIM for one country

When your request sets a Group to isoCountry, the iso_country property of each UsageRecords entry returned includes a unique value for the iso_country.

Return 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

Private beta users might experience different behavior. To prevent disrupting your application by changing the expected response from the API, Twilio added flags added to your account. This section explains these changes.

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

If you used this API before the StartTime and EndTime request parameters requirements, Twilio added a flag to your account. This flag kept your app returning a 200 response instead of throwing an exception. When Twilio accepted your request, the timestamps used to request data from our systems were transformed as described in the following sections. To ensure that data returned matches your request parameters, our team may contact you to adjust your application.

Granularity set to hour

If your StartTime and EndTime values don't fall on a UTC hour boundary, values round up to the next UTC hour.

(information)

For example

You make a UsageRecords API call with the following parameters and values:

Granularity=hour
StartTime=2021-07-01T00:30:00Z (July 1, 2021 12:30am UTC)
EndTime=2021-07-01T10:30:00Z (July 1, 2021 10:30am UTC)

The call returns usage data from 1:00am UTC to 11:00am UTC.

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

Granularity set to day

If your StartTime and EndTime values don't fall on a UTC day boundary, values round up to the next UTC day.

(information)

For example

You make a UsageRecords API call with the following parameters and values:

Granularity=day
StartTime=2021-07-01T00:30:00Z (July 1, 2021 12:30am UTC)
EndTime=2021-07-15T14:00:00Z (July 15, 2021 2:00pm UTC)

The call returns usage data from the start of July 2 through the end of July 15.

To ensure that you receive the expected results, make all requests with Granularity=day with StartTime and EndTime values that fall on midnight UTC like EndTime=2021-07-16T00:00:00Z.

Granularity set to all

Account Usage requests return different results depending on the duration between StartTime and EndTime values.

If your StartTime and EndTime values differ by less than one hour, the API call aggregates all raw usage records.
If your StartTime and EndTime parameters differ by more than one hour, both the StartTime and EndTime parameters round up to the nearest UTC hour as described in the previous section.

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

UsageRecords Resource

Public Beta

Sim vs. SIM

Data considerations

Process data usage

UsageRecord Properties

Return UsageRecords entries

Query parameters

Exclusive end time

Example: Request all usage on single date

Single SIM usage requests versus Account usage requests

Return all UsageRecords

Output

Filter UsageRecords response entries

Return daily UsageRecords for one SIM

Output

Return daily UsageRecords for one Fleet

Output

Return daily UsageRecords for one Network

Output

Return daily UsageRecords for one country

Output

Return daily UsageRecords for one SIM on one Network

Limit UsageRecords to one period of time

Return one Super SIM's daily UsageRecords

Output

Return all daily UsageRecords

Output

Return hourly UsageRecords

Output

Warning

Group UsageRecords by resource type

Private Beta

Return UsageRecords grouped by SIM

Output

Return UsageRecords grouped by Fleet

Output

Return UsageRecords grouped by Network

Output

Return UsageRecords grouped by country

Output

Return UsageRecords grouped by SIM for one country

Output

Legacy Functionality

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

Granularity set to hour

For example

Granularity set to day

For example

Granularity set to all

Filter `UsageRecords` response entries

Limit `UsageRecords` to one period of time