Soracom Air for Cellular

Data Usage

As part of the Soracom platform, you can easily monitor your device's data usage from the User Console.

Checking Data Usage

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to view, then click the Details button.

    https://console.soracom.io

    Subscriber details

  3. A dialog will appear showing the details of the selected IoT SIM. Click the Historical charts tab.

    Historical charts

    The following charts are displayed:

    • Monthly cumulative total - The cumulative total by day for the current month.
    • Data usage - Historical data usage by month, day, or hour.

Changing Bundled Data Plans

For plan-US, plan-NA1, and plan-DU SIMs, a fixed amount of data is bundled with each plan's respective monthly cost. When a device uses up the included monthly data allowance, rather than preventing any further data usage, any additional data usage is billed according to each plan's overage rate, ensuring that your device can continue to operate without disruption.

If you prefer to prevent your device from exceeding its data allowance, you can create an Event Handler to automatically deactivate the SIM once it has reached a specific data usage threshold, as well as automatically reactivate it the following month. In addition to setting a specific threshold, you can also customize an Event Handler to send you an email notification about the data usage, call a webhook, and other actions.

Refer to the Event Handler documentation for more information.

Depending on your device's behavior, you may find it more cost-effective to increase or decrease the data allowance bundled with the plan.

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to update.

  3. Click the Actions menu, then select Update bundle.

    https://console.soracom.io

    Change Bundle

  4. A dialog will appear, allowing you to select which bundle you want to apply to your SIM. Choose the data bundle that you want from the Select bundle dropdown, then click Change.

    Update Bundle

The new bundle will be applied immediately to your SIM.

When changing data bundles, the cost of the larger bundle will be applied to your monthly bill:

  • If upgrading to a higher data bundle, the fee for the higher bundle will apply for that month.
  • If downgrading to a lower bundle, the fee for the higher bundle will apply for that month, and the fee for the lower bundle become effective in the following month.

Any additional data usage exceeding the data allowance included in the applied bundle will be calculated at the end of the month. Refer to the Pricing & Fee Schedule for more information.

Disabling Low Data Remaining Notifications

If desired, you can also disable notifications for low remaining data usage on supported subscriptions.

  1. Click your account menu, then select Email settings.

  2. Scroll down and under Configuration check Stop sending data usage notifications to the primary email address, then click Save.

    https://console.soracom.io

    Disable Notifications

Downloading Data Usage History

You can also download a CSV containing the data usage history (by month or by day) of each SIM in your account.

  1. Login to the User Console. From the Menu, open the Service usage history screen.

  2. Select your desired time frame for usage history then click the Download button.

    https://console.soracom.io

    Service Usage History

    The CSV file may take a couple minutes to prepare. Once it is ready, your browser will automatically begin downloading it.

    Two reports are available:

    • Last 6 months (monthly) - each line contains the total monthly data usage of each SIM in your account, dating back 6 months in addition to the current month
    • Last 90 days (daily) - each line contains the total daily data usage of each SIM in your account, dating back 90 days in addition to the current day

    Regardless of report period, the total data usage is reported in the uploadByteSizeTotal and downloadByteSizeTotal columns. Data amounts in the CSV are reported in bytes. Soracom converts units using 1,024 bytes = 1 kB, and 1,024 kB = 1 MB.

    You can then open the CSV file in a spreadsheet application, such as Microsoft Excel. You can then sort and filter the spreadsheet in order to calculate totals as needed.

    The columns in the CSV are as follows:

    Column Description
    imsi The IMSI (International Mobile Subscriber Identity) of the SIM.
    date The UTC date. Presented as YYYYMM if the report is Monthly, and as YYYYMMDD if the report is Daily.
    type This column will display the type of data connection that was used in the format of COUNTRY-PLAN. Ex. USA-plan01s would refer to data used in the United States on plan01s.
    uploadByteSizeTotal The total number of uploaded bytes that day or month.
    uploadPacketCountTotal The total number of uploaded packets that day or month.
    downloadByteSizeTotal The total number of downloaded bytes that day or month.
    downloadPacketCountTotal The total number of downloaded packets that day or month.
    simId The SIM ID.
    name The user-assigned Name of the SIM.
    (Any Tag) Additional columns will be added here for tags assigned to your SIMs.
    group:groupId The ID of the Group the SIM is assigend to (see Groups).
    group:name The name of the Group the SIM is assigend to (see Groups).

Programmatic Usage

You can also use the Soracom API and Soracom CLI to get the data usage of a particular SIM.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the getAirStats API to get the data usage details of an IoT SIM:

curl -X GET \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/stats/air/subscribers/<IMSI>?from=1543622400&to=1544675800&period=month

You can also specify the period as day or minutes to get the data usage history by day or by minute. When specifying minutes, the minimum interval is approximately 5 minutes.

The amount of usage history available will be limited to the past 18 months (when the usage history is aggregated by month or day), or the past 32 days (when aggregated by minute) when retrieving data through the API

The API will return a JSON response containing data usage stats, according to the request parameters:

[
  {
    "date": "201812",
    "unixtime": 1543622400,
    "dataTrafficStatsMap": {
      "s1.fast": {
        "uploadByteSizeTotal": 9766061,
        "downloadByteSizeTotal": 86596510,
        "uploadPacketSizeTotal": 50094,
        "downloadPacketSizeTotal": 75576
      }
    }
  }
]

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command to get the data usage details of an IoT SIM:

soracom stats air get --imsi <IMSI> --from "1543622400" --to "1544675800" --period "month" --coverage-type g

The CLI will return a response similar to the API example above.