Sim UsageRecord Resource

---

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

The Sim UsageRecords list resource returns usage information for a SIM over a specified period, presented as a list, and aggregated according to the user-provided granularity.

https://programmable-wireless.api.korewireless.com/v1/Sims/<YOUR_SIM_SID>/UsageRecords

---

Data availability

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

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

---

Sim UsageRecords properties

account_sid SID The SID of the Account that created the UsageRecord resource. Pattern:^AC[0-9a-fA-F]{32}$ Min length:34 Max length:34
sim_sid string The SID of the Sim resource that this Usage Record is for.
period object The time period for which usage is reported. Contains start and end properties that describe the period using GMT date-time values specified in ISO 8601 format.
commands object An object that describes the aggregated Commands usage for all SIMs during the specified period. See Commands Usage Object.
data object An object that describes the aggregated Data usage for all SIMs over the period. See Data Usage Object.

Commands Usage Object

The Commands usage object reports usage of Commands for the period.

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

Property Data Type	Description	Empty Value
total Integer	The total number of Commands sent (from_sim) or received (to_sim) by the SIM over the given period.	0
to_sim Integer	The number of Commands received by the SIM (to_sim) throughout the period.	0
from_sim Integer	The number of Commands sent by the SIM (from_sim) throughout the period.	0
home Object	An embedded Commands Usage Object that describes the number of Commands received by the SIM on the home network throughout the period, with keys total, to_sim and from_sim.	null
national_roaming Object	An embedded Commands Usage Object that describes the number of Commands received by the SIM on national roaming partner networks throughout the period, with keys total, to_sim and from_sim.	null
international_roaming Array	An array of Commands Usage Objects, one for each country with usage, that describes the number of Commands received by or sent from the SIM on international roaming partner networks throughout the period, with keys total, to_sim and from_sim.	[]

Data Usage Object

The Data usage object reports usage of Data for the period.

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

Property Data 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 Array	An array of Data Usage Objects, one for each country with usage, that describes the amount of Data consumed by the SIM-connected device on international roaming partner networks throughout the period, with keys total, download, upload and units.	[]

---

Read multiple UsageRecord resources

List Data Usage records for a sim

get

Authorizations

Auth

Path parameters

SidstringRequired

The SID of the Sim resource to read the usage from.

Query parameters

StartstringOptional

Only include usage that has occurred on or after this date. Format is ISO 8601

EndstringOptional

Only include usage that has occurred on or before this date. Format is ISO 8601.

Granularitystring · enumOptional

How to summarize the usage by time. Can be - daily, hourly, or all. A value of all returns one Usage Record that describes the usage for the entire period.

Possible values:

PageSizeinteger · int32Optional

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

PageintegerOptional

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

PageTokenstringOptional

The page token. This is provided by the API.

Responses

200

Data Usage List

application/json

400

Invalid request

application/json

401

Credentials were not provided and are required to access this resource

application/json

403

Credentials were not provided and are required to access this resource

application/json

404

Resource not found

application/json

415

Credentials were not provided and are required to access this resource

application/json

422

Resource not found

application/json

500

Internal Server Error

application/json

503

Server is temporary not available

application/json

get

/v1/Sims/{Sid}/UsageRecords

cURLNodeJsJavaC#PhpPython

curl --location --globoff 'https://programmable-wireless.api.korewireless.com/v1/Sims/<string>/UsageRecords?Start=<string>&End=<string>&Granularity=<string>&PageSize=<integer>&PageToken=<string>' \
--header 'Authorization: Bearer <YOUR_AUTH_TOKEN>'

{
  "usage_records": [
    {
      "period": {
        "start": "text",
        "end": "text"
      },
      "account_sid": "text",
      "commands": {
        "from_sim": 1,
        "to_sim": 1,
        "total": 1,
        "billed": 1,
        "home": {
          "from_sim": 1,
          "to_sim": 1,
          "total": 1,
          "billed": 1,
          "billing_units": "text"
        },
        "national_roaming": {
          "from_sim": 1,
          "to_sim": 1,
          "total": 1,
          "billed": 1,
          "billing_units": "text"
        },
        "international_roaming": [
          {
            "country_code": "text",
            "from_sim": 1,
            "to_sim": 1,
            "total": 1,
            "billed": 1,
            "billing_units": "text"
          }
        ],
        "billing_units": "text"
      },
      "data": {
        "download": 1,
        "upload": 1,
        "total": 1,
        "units": "text",
        "billed": 1,
        "home": {
          "download": 1,
          "upload": 1,
          "total": 1,
          "units": "text",
          "billed": 1,
          "billing_units": "text"
        },
        "national_roaming": {
          "download": 1,
          "upload": 1,
          "total": 1,
          "units": "text",
          "billed": 1,
          "billing_units": "text"
        },
        "international_roaming": [
          {
            "country_code": "text",
            "download": 1,
            "upload": 1,
            "total": 1,
            "units": "text",
            "billed": 1,
            "billing_units": "text"
          }
        ],
        "billing_units": "text"
      },
      "sim_sid": "text"
    }
  ],
  "meta": {
    "page_size": 0,
    "page": 0,
    "first_page_url": "text",
    "previous_page_url": "text",
    "url": "text",
    "key": "text",
    "next_page_url": "text"
  }
}