Usage Records Core Concepts

This page covers the data model of the Usage API (GET /projects/{project}/subscriptions/{subscription}/usage). The Usage API returns aggregated consumption records that can be sliced by time range, country, and roaming status, making it suited for reporting and analytics. For showing users how much of their plan or add-on allowance remains, see the Usage Balances API.

Usage records vs. Usage Balances

The two APIs return different shapes of data for different purposes.

• Usage record = an aggregated consumption row for reporting (e.g. "342 MB data on 2024-03-14 in the US")
• Usage Balance = an allowance meter for end-user display (e.g. "4.2 GB used of 10 GB on the Europe roaming add-on")

Usage records are time-series rows grouped by an aggregation window. They can be broken down by day, billing period, country, or roaming status, which makes them useful for dashboards, charts, and internal analytics. They report total consumption on a subscription and do not attribute usage to individual allowances or add-ons.

Usage Balances track consumption against specific plan and add-on entitlements, with pre-computed used, remaining, and percentage fields. They are designed for building user-facing UI like "you have 3.2 GB left."

The usageRecord object

Each item returned by the Usage API is a usageRecord. It contains consumption totals for a single aggregation window along with contextual metadata.

Preview fields

Labels

The labels object contains contextual metadata. Which fields are populated depends on the active aggregation dimensions.

Querying usage records

Filtering by period

The period query parameter limits results to a specific subscription period number. Periods are integers starting at 1, where period 1 is the first billing cycle after activation. This parameter cannot be combined with start/end.

Filtering by date range

The start and end query parameters accept ISO 8601 dates and must be provided together. They define an inclusive start and exclusive end for the query window. These parameters cannot be combined with period.

If neither period nor start/end is provided, the API defaults to the latest subscription period.

Aggregation

The aggregation query parameter controls how records are grouped. The default is daily.

You can combine dimensions with a comma. daily,country produces one record per day per country. period,roaming produces one record per period per roaming status. The labels fields present in each record match the aggregation dimensions in the request.

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/${SUBSCRIPTION_ID}/usage?aggregation=daily,country" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

Units

All three usage types are returned in every usageRecord object.

Unlike the Usage Balances API, which has a unit field per balance, usage records report all three types in a single object. There is no per-record unit field; data is always bytes, voice is always seconds, and sms is always message count.

Example response

{
  "object": "list",
  "items": [
    {
      "object": "usageRecord",
      "data": 18883100,
      "dataDeviceBytes": 30029300,
      "dataTetheringBytes": 30029300,
      "end": "2021-02-15T00:00:00Z",
      "labels": {
        "country": "US",
        "roaming": "none",
        "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
      },
      "sms": 15,
      "smsInternationalMessages": 6,
      "smsLocalMessages": 6,
      "start": "2021-02-14T00:00:00Z",
      "updatedAt": "2024-02-15T12:13:14Z",
      "voice": 240,
      "voiceInternationalSeconds": 125,
      "voiceLocalSeconds": 6
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

Next Steps

• Usage APIs - Common API requests for Usage Records and Usage Balances.
• Usage Balances Core Concepts - Pre-computed allowance meters for user-facing display.
• Usage Events - Subscribe to webhook events for usage thresholds and data throttling.