# Usage API

This page covers common API requests for the [Usage Balances API][usage-balances-api] for [Usage Balances][usage-balances-core-concepts] and the [Usage API][usage-api] for [Usage Records][usage-records-core-concepts]. 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][usage-balances-core-concepts] and [Usage Records Core Concepts][usage-records-core-concepts] for the full object schemas and field definitions.

## Choosing the right API

| | [**Usage Balances API**][usage-balances-api] for [**Usage Balances**][usage-balances-core-concepts] | [**Usage API**][usage-api] for [**Usage Records**][usage-records-core-concepts] |
|---|---|---|
| **Best for** | [Remaining allowances](#get-current-period-plan-balances-for-a-subscription), progress bars, threshold alerts for in-app display. | [Daily charts, per-country breakdowns](#aggregate-by-day-and-country), [custom aggregation for reporting](#filter-by-date-range). |
| **Data shape** | Pre-computed per-allowance balances with `used`, `remaining`, and percentages - see [Usage Balances Core Concepts][usage-balances-core-concepts]. | Raw time-series records that require client-side aggregation - see [Usage Records Core Concepts][usage-records-core-concepts]. |
| **Usage Attribution** | Usage attributed individually to [each subscription plan or add-on](#fetch-all-current-balances-plan-add-ons). | [Usage attributed to the subscription](#filter-by-subscription-period), no breakdown. |

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

## Usage Balances API

For the complete reference see the [Usage Balances API documentation][usage-balances-api] and [Usage Balances Core Concepts][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`

<CodeGroup title="Get current period subscription plan balances">

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

</CodeGroup>

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

<CodeGroup title="Response - the usage balance of the subscription plan, current period">

```json
{
  "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
}
```

</CodeGroup>

**Note** this returns base-plan balances only. To retrieve add-on balances see [this example](#fetch-all-current-balances-plan-add-ons).

### List Usage Balances

**Endpoint:** `GET /projects/{project}/usageBalances`

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

**Query Parameters:**

| Parameter | Type | Description |
|---|---|---|
| `subscription` | string | Filter by subscription ID (`sub_`) - see [ID Prefixes][usage-balances-ids]. Returns all balances across all periods and source types when used alone. |
| `subscriptionPeriod` | string | Filter by billing period. Requires the `subscription` parameter. Cannot be combined with `subscriptionAddon` - when `subscriptionPeriod` is used, add-on balances will not be returned. |
| `subscriptionAddon` | string | Filter by subscription add-on ID (`sad_`) - see [ID Prefixes][usage-balances-ids]. Can be combined with `subscription` but not with `subscriptionPeriod`. |
| `after` | string | Cursor for forward pagination. Use the value from `moreItemsAfter` in a previous response. |
| `before` | string | Cursor for backward pagination. Use the value from `moreItemsBefore` in a previous response. |

**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:

| Value | Meaning |
|---|---|
| `current` | The subscription's current (most recent) billing period. |
| Positive integer for example `3` | A specific period number. `1` is always the first billing period. |
| Negative integer for example `-1` | Relative lookback from the current period to previous _completed_ billing periods. For example: `-1` = previous period, `-2` = two periods ago, etc. |

**Note** that the `source` field in a [Usage Balances response][usage-balances-source] will contain the positive integer billing period number, if the `source.type` is `subscriptionPeriod`.

<Note type="warning">

`subscriptionPeriod` and `subscriptionAddon` are mutually exclusive. A Usage Balance is sourced from either a period or an add-on. Combining these filters returns an error - [more details here][usage-balances-source].

</Note>

**Error responses:**

| Status | Meaning |
|---|---|
| `403` | Permission denied |
| `404` | Project not found |

### Retrieve a Specific Usage Balance

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

Returns a single Usage Balance by ID.

**Path parameters:**

| Parameter | Description |
|---|---|
| `project` | Gigs [Project ID][projects] |
| `usageBalance` | Usage Balance ID (`ubl_`) - see [ID Prefixes][usage-balances-ids] |

**Error responses:**

| Status | Meaning |
|---|---|
| `403` | Permission denied |
| `404` | Usage Balance or project not found |

### 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`](#fetch-all-current-balances-plan-add-ons) or [filter by `subscriptionAddon` ID](#fetch-add-on-balances-by-add-on-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):

<CodeGroup title="Fetch all current balances">

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

</CodeGroup>

### 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][usage-balances-ids]). Useful for displaying to users like

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

<CodeGroup title="Fetch add-on balances by ID">

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

</CodeGroup>

**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][usage-balances-ids]).

### 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](#subscription-period-special-values).

<CodeGroup title="Previous period balances">

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

</CodeGroup>

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][usage-balances-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][usage-balances-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:

<CodeGroup title="Javascript: find balances covering Germany">

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

</CodeGroup>

---

## Usage API for Usage Records

The [Usage API][usage-api] returns aggregated consumption records grouped by day, country, or billing period. See [Usage Records Core Concepts][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.

<CodeGroup title="List usage records for current period">

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

</CodeGroup>

### 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](#subscription-period-special-values) and cannot be combined with [`start`/`end`](#filter-by-date-range).

<CodeGroup title="Filter usage records by period">

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

</CodeGroup>

### 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`](#filter-by-subscription-period).

<CodeGroup title="Filter usage records by date range">

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

</CodeGroup>

### 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.

<CodeGroup title="Aggregate usage records by country">

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

</CodeGroup>

### 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.

<CodeGroup title="Aggregate usage records by day and country">

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

</CodeGroup>

**Note** that `daily` is the smallest unit of aggregration (see [aggregation][usage-records-aggregation]).

**Error responses:**

| Status | Meaning |
|---|---|
| `404` | Subscription or project not found |
| `422` | Invalid parameter combination (e.g. `period` with `start`/`end`) |

## Next Steps

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

[usage-balances-core-concepts]: /docs/core/usage/usage-balances-core-concepts
[usage-balances-source]: /docs/core/usage/usage-balances-core-concepts#source
[usage-balances-ids]: /docs/core/usage/usage-balances-core-concepts#id-prefixes
[usage-balances-allowance]: /docs/core/usage/usage-balances-core-concepts#allowance
[usage-records-core-concepts]: /docs/core/usage/usage-records-core-concepts
[usage-records-aggregation]: /docs/core/usage/usage-records-core-concepts#aggregation
[usage-api]: /api/latest/core/usage
[usage-balances-api]: /api/latest/core/usage-balances
[usage-events]: /docs/core/usage/usage-events
[usage-balances-testing]: /docs/core/usage/testing-usage-balances
[projects]: /api/latest/core/projects