Provider data balances

Use GET /api/v1/providers/data-balances to monitor upstream data availability from your backend. The response contains one record per provider with a balance observation. Providers without observations are omitted. The endpoint is read-only; operators record observations in the admin panel.

Authentication

Authenticate with a superuser JWT (Authorization: Bearer …) or an API key owned by an active superuser (Authorization: Static …). Staff status alone does not grant access, and browser session cookies are not supported. An impersonation header does not grant a regular API-key owner superuser access. Handle 401 and 403 through the SDK’s normal API error handling.

Read balances

Replace {api_host} and {api_key} with your deployment and a superuser-owned key. Select a language tab for the corresponding SDK call.

RequestGET /providers/data-balances

curl 'https://{api_host}/api/v1/providers/data-balances' \
  --get \
  --header 'Authorization: Static {api_key}' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'offset=0'

import { ProxyRequestClient } from "@proxyrequest/sdk";

const client = ProxyRequestClient.withApiKey(
  "{api_key}", { baseUrl: "https://{api_host}/api/v1" }
);

const result = await client.providers.listDataBalances({
  limit: 20,
  offset: 0,
});

from proxyrequest_sdk import Client

with Client.with_api_key(
    "{api_key}", base_url="https://{api_host}/api/v1"
) as client:
    result = client.providers.list_data_balances(
        limit=20,
        offset=0,
    )

<?php
require __DIR__ . '/vendor/autoload.php';

use ProxyRequest\Client;

$client = Client::withApiKey(
    '{api_key}', 'https://{api_host}/api/v1'
);

$result = $client->providers()->listDataBalances(
    limit: 20,
    offset: 0,
);

Response200 OK

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "checkpoint_id": "00000000-0000-4000-8000-000000000001",
      "provider_id": "provider-one",
      "provider_name": "Example Provider",
      "observed_at": "2026-09-25T08:00:00+00:00",
      "available_bytes": "5497558138880",
      "used_bytes": "1099511627776",
      "remaining_bytes": "4398046511104",
      "remaining_percent": 80,
      "severity": null,
      "freshness": "fresh",
      "error": "",
      "calculated_at": "2026-09-25T08:05:00+00:00",
      "history": [
        {
          "id": "00000000-0000-4000-8000-000000000001",
          "available_bytes": "5497558138880",
          "observed_at": "2026-09-25T08:00:00+00:00",
          "created": "2026-09-25T08:01:00+00:00",
          "created_by": null
        },
        {
          "id": "00000000-0000-4000-8000-000000000002",
          "available_bytes": "1099511627776",
          "observed_at": "2026-09-24T08:00:00+00:00",
          "created": "2026-09-24T08:01:00+00:00",
          "created_by": "operator"
        }
      ]
    }
  ]
}

Replace placeholders in braces with your values. Responses use synthetic example data.Install SDKs API reference →

For JWT authentication, supply a superuser access token:

RequestGET /providers/data-balances

curl 'https://{api_host}/api/v1/providers/data-balances' \
  --get \
  --header 'Authorization: Bearer {access_token}' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'offset=0'

import { ProxyRequestClient } from "@proxyrequest/sdk";

const client = ProxyRequestClient.withBearerToken(
  "{access_token}", { baseUrl: "https://{api_host}/api/v1" }
);

const result = await client.providers.listDataBalances({
  limit: 20,
  offset: 0,
});

from proxyrequest_sdk import Client

with Client.with_bearer_token(
    "{access_token}", base_url="https://{api_host}/api/v1"
) as client:
    result = client.providers.list_data_balances(
        limit=20,
        offset=0,
    )

<?php
require __DIR__ . '/vendor/autoload.php';

use ProxyRequest\Client;

$client = Client::withBearerToken(
    '{access_token}', 'https://{api_host}/api/v1'
);

$result = $client->providers()->listDataBalances(
    limit: 20,
    offset: 0,
);

Response200 OK

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "checkpoint_id": "00000000-0000-4000-8000-000000000001",
      "provider_id": "provider-one",
      "provider_name": "Example Provider",
      "observed_at": "2026-09-25T08:00:00+00:00",
      "available_bytes": "5497558138880",
      "used_bytes": "1099511627776",
      "remaining_bytes": "4398046511104",
      "remaining_percent": 80,
      "severity": null,
      "freshness": "fresh",
      "error": "",
      "calculated_at": "2026-09-25T08:05:00+00:00",
      "history": [
        {
          "id": "00000000-0000-4000-8000-000000000001",
          "available_bytes": "5497558138880",
          "observed_at": "2026-09-25T08:00:00+00:00",
          "created": "2026-09-25T08:01:00+00:00",
          "created_by": null
        },
        {
          "id": "00000000-0000-4000-8000-000000000002",
          "available_bytes": "1099511627776",
          "observed_at": "2026-09-24T08:00:00+00:00",
          "created": "2026-09-24T08:01:00+00:00",
          "created_by": "operator"
        }
      ]
    }
  ]
}

Replace placeholders in braces with your values. Responses use synthetic example data.Install SDKs API reference →

Interpret a balance

Field	Meaning
`provider_id`, `provider_name`	Provider identity; treat the ID as an opaque string.
`checkpoint_id`	The observation used for the current balance, selected by observation time.
`available_bytes`	Balance recorded at `observed_at`, in bytes. This is the calculation’s starting balance.
`used_bytes`	Calculated usage since that observation; `null` until available.
`remaining_bytes`	Calculated remaining balance at `calculated_at`; `null` until available.
`remaining_percent`, `severity`	Remaining percentage and warning level (`warning`, `danger`, or `null`).
`observed_at`	When the starting balance was observed.
`calculated_at`	Time of the last successful calculation, or `null` if none is available.
`freshness`, `error`	Calculation state and an error description when applicable.
`history`	Recent observation records, ordered by creation time, newest first.

All byte amounts, including those in history, are decimal strings. Preserve them as strings or use an exact integer representation for arithmetic. A missing calculation is null, not zero.

The endpoint reads cached calculations; a GET does not trigger a new usage calculation. Check freshness together with calculated_at: fresh is current according to the server’s freshness policy, stale retains an older calculation, and unavailable means no usable calculation exists. Do not present a stale value as a live supplier balance.

Pagination and history

The response envelope is count, results, next, and previous. Use limit and offset, or the SDK’s existing pagination helper, to iterate over providers. History remains nested in each provider record.

Each history entry contains id, available_bytes, observed_at, created, and nullable created_by. Creation time determines history order; observation time determines the current checkpoint, so those orders can differ.

The server returns the latest 10 history entries by default. Operators can change the positive PROVIDER_DATA_BALANCE_HISTORY_LIMIT environment setting. This is a server setting, not a query parameter, and it does not change provider pagination.

See the generated API Reference for the wire contract and Providers SDK Reference for signatures and models.