Usage API

The Connectivity Usage API can be used to query SIM usages. The API is broken down into two sections: the aggregate API and the time series API.

The aggregate API is used to query usages at a monthly granularity. The usages can be queried by account, all SIMs, or a single SIM. Additionally, usages can be grouped by markers.

The time series API is used to query usages at a daily granularity over a time range. The usages can be queried by account, SIM, or markers.

All requests to the connectivity usage api must be authenticated and have the scope CONNECT:READ, unless otherwise noted. Each response body is returned as json.

Usage model

The following is an example of the usage model used in all aggregate and time-series usage endpoints. The model includes uploaded, downloaded, and total bytes used. The date represents the start of when the usage was aggregated.

{
    "total": 176069867,
    "unit": "bytes",
    "upload": 94866194,
    "date": "2020-08-01T00:00:00Z",
    "download": 81203673
}

Aggregate usage model

The following is an example of the aggregate usage model used in all the aggregate usage endpoints.

The aggregate usage model includes a basic SIM and marker objects. The SIM object simply includes the iccid, while the marker object includes both the key and value. The SIM object is only present when the usages are grouped by SIMs (i.e., the Multi-SIM and SIM endpoints). The marker object is only present when the marker query parameter is used in any of the aggregate usage endpoints.

{
  "marker": {
      "key": "device-type",
      "value": "D450"
  },
  "sim": {
    "iccid": "iccid1"
  },
  "usage": {
      "total": 176069867,
      "unit": "bytes",
      "upload": 94866194,
      "date": "2020-08-01T00:00:00Z",
      "download": 81203673
  }
}

Aggregate usage

The Aggregate usage API is used to get high level, monthly usage data. The usages can be broken down by Account or SIM and grouped by markers.

All Aggregate endpoints require a date time parameter. Each usage record is aggregated over the month of the given date. Each request will return a single usage for each resource and may return multiple resources.

A resource is a SIM or an Account with an associated marker. A SIM or Account can have multiple usage records over the same time period with different markers.

All Aggregate endpoints can be sorted by passing upload, download, or total to the orderByColumn query parameter. By default, resources are sorted by total usage in descending order. This can be overridden by setting the orderBy query parameter to asc.

Query parameters

The following query parameters are allowed on all aggregate usage endpoints

Name	Type	Description
date	`string`	RFC339 formatted string, representing the date for the usages aggregated by month
orderBy (optional)	`string`	Direction to sort usages by. Acceptable values are `asc` and `desc`. This is `desc` by default
orderByColumn (optional)	`string`	Column to sort by. Acceptable values are `total`, `upload`, and `download`. This is `total` by default
marker (optional)	`string`	The marker key to group usages by. Check out markers for acceptable values

GET Aggregate account usage

https://api.bymason.com/beta/{fleet}/data/aggregate/usage?date={date}

This endpoint will fetch the usage records at the account level. A query accepts an optional marker parameter. This must be a valid marker key. If given, the response usage records will be split by the given marker. Each usage record will correspond to one of the keys value.

If marker is omitted, there will be a single usage record representing the amount of data the account used during the time period.

The response data is a paginated list of aggregate usages. If a marker is specified, each usage will have a marker object attached to it.

Required API key scope(s)

connect:read

For more information on scoping API keys, visit our guide for creating API keys

Basic example

Basic Aggregate usage will fetch account level usage aggregated for the given month. The response data is a paginated list of usages aggregated by the month. For basic usage, there will be a single usage.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/aggregate/usage?date=2020-08-01T0:00:00-00:00

{
    "nextPage": "..",
    "prevPage": "..",
    "data" : [
        {
          "usage": {
              "total": 176069867,
              "unit": "bytes",
              "upload": 94866194,
              "date": "2020-08-01T00:00:00Z",
              "download": 81203673
          }
        }
    ]
}

Advanced usage

The Aggregate API can group usages by a marker. This will return a paginated list of aggregate usages, where each usage has a marker object attached to it. The example below shows how to query usages by device type. If a SIM is not in a Mason device during the given month, its usages will not appear in the results.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/aggregate/usage?date=2020-08-01T0:00:00-00:00&marker=device-type

{
    "nextPage": "..",
    "prevPage": "..",
    "data" : [ 
        {
            "marker": {
                "key": "device-type",
                "value": "D450"
            },
            "usage": {
                "total": 176069867,
                "unit": "bytes",
                "upload": 94866194,
                "date": "2020-08-01T00:00:00Z",
                "download": 81203673
            }
        },
        {
            "marker": {
                "key": "device-type",
                "value": "G450"
            },
            "usage":{
                "total": 176069867,
                "unit": "bytes",
                "upload": 94866194,
                "date": "2020-08-01T00:00:00Z",
                "download": 81203673
            }
        }
    ]
}

GET Aggregate Multi-SIM usage

https://api.bymason.com/beta/{fleet}/data/aggregate/usage/sim?marker={marker}&date={date}

This endpoint is used to get high level usage information about all SIMs in an account. The marker query parameter is optional. If specified, it will group usages by SIM and the marker value for the time period. It is possible for an iccid to appear multiple times under different values. For example, if the marker was set to device-type and iccid1 was in a G450, but moved to a D450 during the input time range, the result will include two usages for iccid1: one marked with D450, the second marked with G450.

If marker is omitted, then this API will simply return the total data used by each SIM over the given time period.

The response data is a paginated list of aggregate usages. If a marker is specified, each usage will have a marker object attached to it.

Required API key scope(s)

connect:read

For more information on scoping API keys, visit our guide for creating API keys

Query parameters

Name	Type	Description
date	`string`	RFC339 formatted string, representing the date for the usages aggregated by month
orderBy (optional)	`string`	Direction to sort usages by. Acceptable values are `asc` and `desc`. This is `desc` by default
orderByColumn (optional)	`string`	Column to sort by. Acceptable values are `total`, `upload`, and `download`. This is `total` by default
marker (optional)	`string`	The marker key to group usages by. Check out markers for acceptable values

Basic usage

The basic usage of the Multi-SIM endpoint will fetch the amount of data each SIM has used over the given time period.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/aggregate/usage/sim?date=2020-08-01T0:00:00-00:00

{
    "nextPage": "..",
    "prevPage": "..",
    "data" : [
        {
          "sim": {
            "iccid": "iccid1"
          },
          "usage": {
              "total": 176069867,
              "unit": "bytes",
              "upload": 94866194,
              "date": "2020-08-01T00:00:00Z",
              "download": 81203673
          }
        },
        {
        "sim": {
            "iccid": "iccid2"
          },
          "usage": {
              "total": 176069867,
              "unit": "bytes",
              "upload": 94866194,
              "date": "2020-08-01T00:00:00Z",
              "download": 81203673
          }
        }
    ]
}

Advanced usage

The Aggregate API can group usages by a marker. This will return a pagintated list of aggregate usages, where each usage has a marker value associated with it. The example below shows how to query SIM usages by device type. If a SIM is not in a Mason device, there will not be a marker associated with the usage. If a SIM was moved to a different device in the given time range, it will appear multiple times in the results.

The advanced usage of the Multi SIM endpoint will fetch the amount of data each SIM has used over the given time period grouped the given marker.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/aggregate/usage/sim?date=2020-08-01T0:00:00-00:00&marker=device-type

{
    "nextPage": "..",
    "prevPage": "..",
    "data" : [
        {
           "marker": {
                "key": "device-type",
                "value": "G450"
            },
            "sim": {
                "iccid": "iccid1"
            },
            "usage": {
                "total": 176069867,
                "unit": "bytes",
                "upload": 94866194,
                "date": "2020-05-01T00:00:00Z",
                "download": 81203673
            }
        },
        {
            "marker": {
                "key": "device-type",
                "value": "D450"
            },
            "sim": {
              "iccid": "iccid2"
            },
            "usage": {
                "total": 176069867,
                "unit": "bytes",
                "upload": 94866194,
                "date": "2020-05-01T00:00:00Z",
                "download": 81203673
            }
        }
    ]
}

GET Aggregate SIM usage

https://api.bymason.com/beta/{fleet}/data/aggregate/usage/sim/{iccid}?date={date}

The aggregate SIM endpoint is the same as the Multi SIM aggregate endpoint, except that it accepts an iccid as an url path parameter. It will only return usages for the given iccid.

The response data is a paginated list of aggregate usages. If a marker is specified, each usage will have a marker object attached to it.

Required API key scope(s)

connect:read

For more information on scoping API keys, visit our guide for creating API keys

Query parameters

Name	Type	Description
date	`string`	RFC339 formatted string, representing the date for the usages aggregated by month
orderBy (optional)	`string`	Direction to sort usages by. Acceptable values are `asc` and `desc`. This is `desc` by default
orderByColumn (optional)	`string`	Column to sort by. Acceptable values are `total`, `upload`, and `download`. This is `total` by default
marker (optional)	`string`	The marker key to group usages by. Check out markers for acceptable values

Basic usage

The basic usage of this endpoint will fetch the usage aggregated by the given month for the specified SIM.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/aggregate/usage/sim/iccid1?date=2020-08-01T0:00:00-00:00

{
    "nextPage": "..",
    "prevPage": "..",
    "data" : [
        {
          "sim": {
            "iccid": "iccid1"
          },
          "usage": {
              "total": 176069867,
              "unit": "bytes",
              "upload": 94866194,
              "date": "2020-08-01T00:00:00Z",
              "download": 81203673
          }
        }
    ]
}

Advanced usage

The advanced usage of this endpoint will fetch the usage aggregated by the given month for the specified SIM grouped by the specific marker values for the given marker. The example below groups the SIMs' usage based on the type of device it was in.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/aggregate/usage/sim?date=2020-08-01T0:00:00-00:00&marker=device-type

{
    "nextPage": "..",
    "prevPage": "..",
    "data" : [
        {
          "sim": {
            "iccid": "iccid1"
          },
          "marker": {
                "key": "device-type",
                "value": "G450"
            },
          "usage": {
              "total": 176069867,
              "unit": "bytes",
              "upload": 94866194,
              "date": "2020-08-01T00:00:00Z",
              "download": 81203673
          }
        },
        {
          "sim": {
            "iccid": "iccid1"
          },
          "marker": {
                "key": "device-type",
                "value": "D450"
            },
          "usage": {
              "total": 176069867,
              "unit": "bytes",
              "upload": 94866194,
              "date": "2020-08-01T00:00:00Z",
              "download": 81203673
          }
        }
    ]
}

Time series usage

The time series usage apis are used to get daily usage data about a specific resource. Time series usages can also be aggregated by marker values.

GET Time series account usage

https://api.bymason.com/beta/default/data/series/usage?marker={marker}&markerValue={markerValue}&start={start}&end={end}

The time series account endpoint is used to get time series usage data from the account. The time series data will be queried over the specified time range and aggregated by day.

The marker and markerValue are optional. If specified, it will query the account for the specific marker only. If omitted, it will fetch all of the account usage records over the time period.

The response data is a paginated list of usages.

Required API key scope(s)

connect:read

For more information on scoping API keys, visit our guide for creating API keys

Query parameters

Name	Type	Description
`start` (required)	`string`	RFC339 formatted string, representing inclusive usage start date
`end` (required)	`string`	RFC339 formatted string, representing exclusive usage start date
`marker` (optional)	`string`	Optional marker key used to group usages by a specific marker. Required if `markerValue` is present
`markerValue` (optional)	`string`	Optional marker value used to group usages by a specific marker. Required if `marker` is present

Basic usage

The basic usage of the time series usage is to simply specify the start and end query parameters. This will aggregate all usages at a daily interval for the specified time range.

The response data is a paginated list of usages.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/series/usage/sim?start=2020-08-01T00:00:00Z&end=2020-08-05T00:00:00Z0

{
  "data": [
    {
      "day": "2020-08-01T00:00:00Z",
      "download": 24523510,
      "total": 58854641,
      "unit": "bytes",
      "upload": 34331131
    },
    {
      "day": "2020-08-02T00:00:00Z",
      "download": 24523510,
      "total": 58854641,
      "unit": "bytes",
      "upload": 34331131
    },
    {
      "day": "2020-08-03T00:00:00Z",
      "download": 24655370,
      "total": 47749006,
      "unit": "bytes",
      "upload": 23093636
    },
    {
      "day": "2020-08-04T00:00:00Z",
      "download": 22649580,
      "total": 50789712,
      "unit": "bytes",
      "upload": 28140132
    }
  ]
}

Advanced usage

The time series usage endpoint also accepts a marker and a markerValue. If specified, the usages will be aggregated according to the given marker.

The example below will fetch the time series usage for all SIMS in D450 devices.

The response data is a paginated list of usages.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/series/usage/sim?start=2020-08-01T00:00:00Z&end=2020-08-05T00:00:00Z&marker=device-type&markerValue=D450

{
  "data": [
    {
      "day": "2020-08-01T00:00:00Z",
      "download": 24523510,
      "total": 58854641,
      "unit": "bytes",
      "upload": 34331131
    },
    {
      "day": "2020-08-02T00:00:00Z",
      "download": 24523510,
      "total": 58854641,
      "unit": "bytes",
      "upload": 34331131
    },
    {
      "day": "2020-08-03T00:00:00Z",
      "download": 24655370,
      "total": 47749006,
      "unit": "bytes",
      "upload": 23093636
    },
    {
      "day": "2020-08-04T00:00:00Z",
      "download": 22649580,
      "total": 50789712,
      "unit": "bytes",
      "upload": 28140132
    },
    {
      "day": "2020-08-05T00:00:00Z",
      "download": 22649580,
      "total": 50789712,
      "unit": "bytes",
      "upload": 28140132
    }
  ]
}

GET Time series SIM usage

https://api.bymason.com/beta/default/data/series/usage/{iccid}?marker={marker}&markerValue={markerValue}&start={start}&end={end}

The time series SIM endpoint is used to get time series usage data from a specific SIM. The time series data will be queried over the specified time range and aggregated by day.

The marker and markerValue are optional. If specified, it will query the iccid for the specific marker only. If omitted, it will fetch all of the iccid usage records over the time period.

The response data is a paginated list of usages.

Required API key scope(s)

connect:read

For more information on scoping API keys, visit our guide for creating API keys

Basic usage

The basic usage of the time series SIM usage is to simply specify the start and end query parameters. This will aggregate all usages for the specified SIM at a daily interval over the specified time range.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/series/usage/sim/iccid1?start=2020-08-01T00:00:00Z&end=2020-08-05T00:00:00Z

{
  "data": [
    {
      "day": "2020-08-01T00:00:00Z",
      "download": 24523510,
      "total": 58854641,
      "unit": "bytes",
      "upload": 34331131
    },
    {
      "day": "2020-08-02T00:00:00Z",
      "download": 24523510,
      "total": 58854641,
      "unit": "bytes",
      "upload": 34331131
    },
    {
      "day": "2020-08-03T00:00:00Z",
      "download": 24655370,
      "total": 47749006,
      "unit": "bytes",
      "upload": 23093636
    },
    {
      "day": "2020-08-04T00:00:00Z",
      "download": 22649580,
      "total": 50789712,
      "unit": "bytes",
      "upload": 28140132
    },
    {
      "day": "2020-08-05T00:00:00Z",
      "download": 22649580,
      "total": 50789712,
      "unit": "bytes",
      "upload": 28140132
    },
  ]
}

Advanced usage

The advanced usage of this endpoint can aggregate usage from a specific SIM with a specific marker value specified. The following example will query the time series usage for iccid1 while it was in a D450 Mason device.

The response data is a paginated list of usages.

CURL JS

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/beta/default/data/series/usage/sim/iccid1?start=2020-08-01T00:00:00Z&end=2020-08-05T00:00:00Z&marker=device-type&markerValue=D450

{
  "data": [
    {
      "day": "2020-08-01T00:00:00Z",
      "download": 24523510,
      "total": 58854641,
      "unit": "bytes",
      "upload": 34331131
    },
    {
      "day": "2020-08-02T00:00:00Z",
      "download": 24523510,
      "total": 58854641,
      "unit": "bytes",
      "upload": 34331131
    },
    {
      "day": "2020-08-03T00:00:00Z",
      "download": 24655370,
      "total": 47749006,
      "unit": "bytes",
      "upload": 23093636
    },
    {
      "day": "2020-08-04T00:00:00Z",
      "download": 22649580,
      "total": 50789712,
      "unit": "bytes",
      "upload": 28140132
    },
    {
      "day": "2020-08-05T00:00:00Z",
      "download": 22649580,
      "total": 50789712,
      "unit": "bytes",
      "upload": 28140132
    }
  ]
}