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 Air 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-NA1 (Global coverage) and plan-DU (Japan coverage) 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 accorrding 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.


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. Click your account menu, then select Billing.

  2. From the Bills tab, locate the Download traffic stats as CSV panel, and click the Download button.

    https://console.soracom.io

    Download Air stats CSV

    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,204 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.


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 Air 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 and 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 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 Air 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.