LogoLogo
ProductsDevelopersAPI ReferenceContact Us
API Reference
API Reference
  • Overview
  • Products
    • Super SIM
      • Sim Resource
        • Sim BillingPeriod subresource
      • ESimProfile Resource
      • Fleet Resource
      • NetworkAccessProfile Resource
        • NetworkAccessProfile Network Subresource
      • Network Resource
      • SettingsUpdates Resource
      • Usage Record Resource
      • SMSCommand Resource
      • IPCommand Resource
    • Programmable Wireless
      • Account UsageRecord Resource
      • Command Resource
      • DataSession Resource
      • RatePlan Resource
      • Wireless Sim Resource
      • Sim UsageRecord Resource
  • Global Resources
    • API Clients
      • Ping
      • Clients
    • Identity and Access Management
      • Account
    • Webhook
On this page

Was this helpful?

  1. Products
  2. Programmable Wireless

Account UsageRecord Resource

PreviousProgrammable WirelessNextCommand Resource

Last updated 5 months ago

Was this helpful?

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

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

https://programmable-wireless.api.korewireless.com/v1/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.


Usage Record Properties

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

account_sid SID

The SID of the Account that created the AccountUsageRecord resource.

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

Min length:34

Max length:34

commands object

data object


Commands Usage Object

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

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

HTTP GET

Returns a list of Usage Records for an account.

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.

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.

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 format.

An object that describes the aggregated Commands usage for all SIMs during the specified period. See .

An object that describes the aggregated Data usage for all SIMs over the period. See .

SIM Usage Records
ISO 8601
Commands Usage Object
Data Usage Object

List Data Usage records for an account

get
Authorizations
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
409
Resource not found
application/json
415
Resource not found
application/json
422
Resource not found
application/json
500
Internal Server Error
application/json
503
Server is temporary not available
application/json
get
curl --location --globoff 'https://programmable-wireless.api.korewireless.com/v1/UsageRecords?Start=<string>&End=<string>&Granularity=<string>&PageSize=<integer>&Page=<string>&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"
      }
    }
  ],
  "meta": {
    "page_size": 0,
    "page": 0,
    "first_page_url": "text",
    "previous_page_url": "text",
    "url": "text",
    "key": "text",
    "next_page_url": "text"
  }
}
  • Data availability
  • Retention period
  • Usage Record Properties
  • Commands Usage Object
  • Data Usage Object
  • List all Usage Records for an Account
  • GETList Data Usage records for an account