# Account UsageRecord Resource

{% hint style="info" %}
The **Usage Records** resource returns aggregated usage for all SIMs on an Account. To retrieve usage for a single SIM, use the [SIM Usage Records](https://docs.korewireless.com/en-us/api/products/programmable-wireless/sim-usagerecord-resource) resource.
{% endhint %}

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

```bash
https://programmable-wireless.api.korewireless.com/v1/UsageRecords
```

***

## Data availability <a href="#data-availability" id="data-availability"></a>

Data records used to charge your account and populate this resource are not delivered in real-time and can be delayed due to both regular and unplanned maintenance at our carrier partners. Usage may not be reflected from this resource for up to **24 hours** from when it occurred. All usage will typically be processed within 48 hours from when it occurred.

***

## Retention period <a href="#retention-period" id="retention-period"></a>

Usage information will be retained for 18 months, after which it will be deleted. Querying usage records more than 18 months old can result in incomplete data.

***

## Usage Record Properties <a href="#usage-record-properties" id="usage-record-properties"></a>

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

| <p><strong>account\_sid</strong>  SID                                                                                                                                    </p><p>The SID of the Account that created the AccountUsageRecord resource.</p><p>Pattern:<code>^AC\[0-9a-fA-F]{32}$</code></p><p>Min length:<code>34</code></p><p>Max length:<code>34</code></p>                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><strong>period</strong> object                                                                                                                                         <br>The time period for which usage is reported. Contains <code>start</code> and <code>end</code> properties that describe the period using GMT date-time values specified in <a href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO 8601</a> format.</p> |
| <p><strong>commands</strong> object                                                                                                          </p><p>An object that describes the aggregated Commands usage for all SIMs during the specified period. See <a href="#commands-usage-object">Commands Usage Object</a>.</p>                                                                                                                          |
| <p>data object                                                                                                                   </p><p>An object that describes the aggregated Data usage for all SIMs over the period. See <a href="#data-usage-object">Data Usage Object</a>.</p>                                                                                                                                                              |

***

### Commands Usage Object <a href="#commands-usage-object" id="commands-usage-object"></a>

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

The Commands Usage object is presented as a tree-like structure. For example, the `total` value from the `home`, `national_roaming`, and `international_roaming` child objects sum to the `total` value of the top level `commands` object. The same computations are done for the `to_sim` and `from_sim` parameters in the top level object.

| Property                | Type    | Description                                                                                                                                                                                                                     | Empty Value |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `total`                 | Integer | The total number of Commands sent (`from_sim`) or received (`to_sim`) by all SIMs linked to the account over the given period.                                                                                                  | 0           |
| `to_sim`                | Integer | The number of Commands received by all SIMs linked to the account (`to_sim`) throughout the period.                                                                                                                             | 0           |
| `from_sim`              | Integer | The number of Commands sent by all SIMs linked to the account (`from_sim`) throughout the period.                                                                                                                               | 0           |
| `home`                  | Object  | An embedded Commands Usage Object that describes the number of Commands received by all SIMs linked to the account on the home network throughout the period, with keys `total`, `to_sim` and `from_sim`.                       | null        |
| `national_roaming`      | Object  | An embedded Commands Usage Object that describes the number of Commands received by all SIMs linked to the account on national roaming partner networks throughout the period, with keys `total`, `to_sim` and `from_sim`.      | null        |
| `international_roaming` | Object  | An embedded Commands Usage Object that describes the number of Commands received by all SIMs linked to the account on international roaming partner networks throughout the period, with keys `total`, `to_sim` and `from_sim`. | \[]         |

### Data Usage Object <a href="#data-usage-object" id="data-usage-object"></a>

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

The Data Usage object is presented as a tree-like structure. For example, the `total` value from the `home` child object and the `national_roaming` child object sum to the `total` value of the top level `data` object. This is the same for the `download` and `upload` parameters.

| Property                | Type    | Description                                                                                                                                                                                                                | Empty Value |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `total`                 | Integer | The total amount of Data consumed (downloaded and uploaded) by the SIM-connected device throughout the period.                                                                                                             | 0           |
| `download`              | Integer | The amount of Data downloaded by the SIM-connected device throughout the period.                                                                                                                                           | 0           |
| `upload`                | Integer | The amount of Data uploaded by SIM-connected device throughout the period.                                                                                                                                                 | 0           |
| `units`                 | String  | The units in which data usage is reported for the current object. Most often 'bytes'.                                                                                                                                      | N/A         |
| `home`                  | Object  | An embedded Data Usage Object that describes the amount of Data consumed by the SIM-connected device on the home network throughout the period, with keys `total`, `download`, `upload` and `units`.                       | null        |
| `national_roaming`      | Object  | An embedded Data Usage Object that describes the amount of Data consumed by the SIM-connected device on national roaming partner networks throughout the period, with keys `total`, `download`, `upload` and `units`.      | null        |
| `international_roaming` | Object  | An embedded Data Usage Object that describes the amount of Data consumed by the SIM-connected device on international roaming partner networks throughout the period, with keys `total`, `download`, `upload` and `units`. | null        |

***

### List all Usage Records for an Account <a href="#list-all-usage-records-for-an-account" id="list-all-usage-records-for-an-account"></a>

#### HTTP GET <a href="#list-get" id="list-get"></a>

Returns a list of Usage Records for an account.

{% hint style="danger" %}
Usage information will be retained for **18 months** , after which it will be deleted. Querying usage records older than 18 months can result in incomplete data.
{% endhint %}

{% openapi src="<https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20(alf).yaml?alt=media&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341>" path="/v1/UsageRecords" method="get" %}
[openapi3\_0 (alf).yaml](https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20\(alf\).yaml?alt=media\&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341)
{% endopenapi %}

#### HTTP POST <a href="#list-post" id="list-post"></a>

Not supported.

#### HTTP PUT <a href="#list-put" id="list-put"></a>

Not supported.

#### HTTP DELETE <a href="#list-delete" id="list-delete"></a>

Not supported.