Usage API

This page covers common API requests for the Usage Balances API for Usage Balances and the Usage API for Usage Records. The Usage Balances API provides pre-computed allowance meters for user-facing display, including remaining data, percentages, and threshold alerts. The Usage API returns aggregated consumption records for reporting, charts, and per-country breakdowns. See Usage Balances Core Concepts and Usage Records Core Concepts for the full object schemas and field definitions.

Choosing the right API

Start with the Usage Balances API unless you need time-series granularity or per-country breakdowns: the Usage API remains available for those cases.

Usage Balances API

For the complete reference see the Usage Balances API documentation and Usage Balances Core Concepts to understand the API responses.

Get Current Period Plan Balances for a Subscription

The most common call - get current period balances for subscription plans:

Endpoint: /projects/{project}/usageBalances/?subscription={subscription}&subscriptionPeriod=current

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/usageBalances?subscription=${SUBSCRIPTION_ID}&subscriptionPeriod=current" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

The response is a paginated list of Usage Balance objects, one per allowance on the subscription's plan for the current billing period:

{
  "object": "list",
  "items": [
    {
      "object": "usageBalance",
      "id": "ubl_0V9n0zo90CE0NuvcsN0j88",
      "allowance": {
        "object": "allowance",
        "id": "alw_0SNlurA049MEWV3OMTRrGKbd99GH",
        "name": "Roaming data in Europe",
        "type": "data",
        "coverage": {
          "object": "coverage",
          "id": "eu",
          "countries": ["DE", "FR", "IT", "ES"],
          "name": "Europe"
        },
        "limit": 10000000000,
        "unit": "bytes"
      },
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "source": {
        "type": "subscriptionPeriod",
        "subscriptionPeriod": 4
      },
      "unit": "bytes",
      "used": 4200000000,
      "limit": 10000000000,
      "remaining": 5800000000,
      "usedPercent": 42,
      "remainingPercent": 58,
      "usableFrom": "2026-01-03T13:41:24Z",
      "usableUntil": "2026-02-03T13:41:24Z"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

Note this returns base-plan balances only. To retrieve add-on balances see this example.

List Usage Balances

Endpoint: GET /projects/{project}/usageBalances

Returns Usage Balances matching the given filters. The response is a paginated list.

Query Parameters:

Note that if no subscription plans or add-on balances match the query, the API will return an empty list of results.

Subscription Period Special Values:

The subscriptionPeriod parameter accepts the following arguments:

Note that the source field in a Usage Balances response will contain the positive integer billing period number, if the source.type is subscriptionPeriod.

Error responses:

Retrieve a Specific Usage Balance

Endpoint: GET /projects/{project}/usageBalances/{usageBalance}

Returns a single Usage Balance by ID.

Path parameters:

Error responses:

Show current subscription plan usage for a user

Endpoint: GET /projects/{project}/usageBalances?subscription={subscription}&subscriptionPeriod=current

• Filtering by subscriptionPeriod=current returns period-sourced, subscription plan balances for the current billing cycle. It does not include add-on-sourced balances.
• To include add-ons, either omit subscriptionPeriod or filter by subscriptionAddon ID.

Fetch all current balances (plan + add-ons)

Endpoint: GET /projects/{project}/usageBalances?subscription={subscription}

To get both the current base-plan and all add-on balances (active and pending):

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/usageBalances?subscription=${SUBSCRIPTION_ID}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

Fetch add-on balances by add-on ID

Endpoint: GET /projects/{project}/usageBalances?subscription={subscription}&subscriptionAddon={subscriptionAddon}

You can fetch all add-on balances, using the add-on ID sad_ (see ID Prefixes). Useful for displaying to users like

you have 3.2 GB remaining on your 5 GB European Roaming Top Up

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/usageBalances?subscription=${SUBSCRIPTION_ID}&subscriptionAddon=${SUBSCRIPTION_ADDON_ID}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

Note: this could return multiple add-on balances, as a user may have purchased the same add-on multiple times. Each add-on purchase creates its own set of Usage Balances with independent used, remaining, and validity windows. Buying the same add-on product twice creates two separate sets of balances, each with the same sad_ ID but different ubl_ IDs (see ID Prefixes).

View usage history for a previous period

Endpoint: GET /projects/{project}/usageBalances?subscription={subscription}&subscriptionPeriod={subscriptionPeriod}

You can fetch subscription plan balances for previous billing cycles using the subscriptionPeriod special values.

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/usageBalances?subscription=${SUBSCRIPTION_ID}&subscriptionPeriod=-1" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

You can return balances from the previous billing period using negative integers (e.g. -2) for two periods ago, a specific period number (e.g. 3) for an absolute lookup (bearing in mind 1 is always the first billing cycle) or current for the current billing cycle. The Source field in the response will contain the absolute billing period integer. The fields usableFrom and usableUntil in the response will give you the date and time of the beginning and end of the billing cycle or return null if the plan is not yet active.

Note that add-on balances are not returned, if the subscriptionPeriod query parameter is used, as add-ons don't have billing cycles.

Filter by country (client-side)

There is no server-side country filter on the Usage Balances endpoint but in the Allowance of each balance object it includes the coverage field: allowance.coverage.countries (an array of ISO 3166-1 alpha-2 codes). This can be used to filter client-side, to find balances covering a given country:

const balances = response.items;
const germanyBalances = balances.filter(b =>
  b.allowance.coverage.countries.includes("DE")
);

Usage API for Usage Records

The Usage API returns aggregated consumption records grouped by day, country, or billing period. See Usage Records Core Concepts for the full object schema, aggregation modes, and field definitions.

Endpoint: GET /projects/{project}/subscriptions/{subscription}/usage

List usage records

Endpoint: GET /projects/{project}/subscriptions/{subscription}/usage

The default call returns daily-aggregated records for the current subscription period.

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

Filter by subscription period

Endpoint: GET /projects/{project}/subscriptions/{subscription}/usage?period={period}

Use period to limit results to a specific billing period number (positive integer only starting at 1). Note that this does not support the current or negative integer values, seen in the Usage Balances API and cannot be combined with start/end.

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

Filter by date range

Endpoint: GET /projects/{project}/subscriptions/{subscription}/usage?start={start}&end={end}

Use start and end (both required, ISO 8601 dates). Cannot be combined with period.

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/${SUBSCRIPTION_ID}/usage?start=2026-01-01&end=2026-02-01" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

Aggregate by country

Endpoint: GET /projects/{project}/subscriptions/{subscription}/usage?aggregation=country

Use aggregation=country to get one record per country. Each record's labels.country field identifies the country.

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

Aggregate by day and country

Endpoint: GET /projects/{project}/subscriptions/{subscription}/usage?aggregation=daily,country

Combine dimensions with a comma. daily,country produces one record per day per country. The labels fields on each record reflect the active dimensions.

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}"

Note that daily is the smallest unit of aggregration (see aggregation).

Error responses:

Next Steps

• Usage Balances Core Concepts - Covers the core concepts of the Usage Balances object model.
• Usage Records Core Concepts - Covers the usageRecord object, aggregation modes, filtering and labels.
• Usage Events - Subscribe to webhook events for usage thresholds, first-use detection, and data throttling on Gigs subscriptions.
• Testing Usage Balances - How to test and simulate usage on Usage Balances.