> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Management API: Usage

Last updated 2 November 2026

The account's rated usage. [The overview](https://tonbo.dev/docs/reference/management.md) covers what every operation shares: authentication, roles, errors, pagination, idempotency and If-Match.

- [`GET /usage`](#get-usage) Read the account's rated usage of one month
- [`GET /usage/series`](#get-usage-series) Read the account's spend day by day, or hour by hour
- [`GET /usage/today`](#get-usage-today) Read the account's writes of yesterday and today, hourly
- [`GET /usage/databases`](#list-database-usage) Read each database's usage of one month at list price
- [`GET /usage/streams`](#list-stream-usage) Read each stream's usage of one month at list price
- [Objects](#objects): [DatabaseUsage](#schema-database-usage), [DatabaseUsageAmounts](#schema-database-usage-amounts), [SpendAmounts](#schema-spend-amounts), [StreamUsage](#schema-stream-usage), [Usage](#schema-usage), [UsageSeries](#schema-usage-series), [UsageSeriesWindow](#schema-usage-series-window), [UsageToday](#schema-usage-today) and [WritePoint](#schema-write-point)

## Read the account's rated usage of one month

`GET /v1/usage` · CLI: `tonbo usage show`

Needs [`usage.read`](https://tonbo.dev/docs/reference/management.md#capability-usage-read), which `owner` and `admin` hold. A narrowed key may not.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `period` | query | string | no | The calendar month in UTC; the current month when omitted. Matches `^[0-9]{4}-(0[1-9]\|1[0-2])$`. |

### Response

| Status | Answer |
| --- | --- |
| `200` | Usage |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [Usage](https://tonbo.dev/docs/reference/management/usage.md#schema-usage) | yes |  |

| Header | Status | Description |
| --- | --- | --- |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429 | Seconds before the client should retry. |

**Example 200 body**

```json
{
  "data": {
    "period": "2026-11",
    "currency": "usd",
    "total_micros": 1,
    "lines": [
      {
        "product": "<product>",
        "region": "<region>",
        "dimension": "<dimension>",
        "model": "<model>",
        "quantity": "<quantity>",
        "amount_micros": 1
      }
    ]
  }
}
```

### Errors

| Status | Code | When | Send again | What to do |
| --- | --- | --- | --- | --- |
| `401` | [`exchange_required`](https://tonbo.dev/docs/reference/management.md#exchange_required) | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#exchange_required)) |
| `401` | [`unauthenticated`](https://tonbo.dev/docs/reference/management.md#unauthenticated) | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#unauthenticated)) |
| `403` | [`forbidden`](https://tonbo.dev/docs/reference/management.md#forbidden) | The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may. | No | Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#forbidden)) |
| `422` | [`validation_error`](https://tonbo.dev/docs/reference/management.md#validation_error) | A parameter, header or body field breaks its rule; `errors` names each field. | No | Correct the fields `errors` names; the operation’s reference gives each one’s rule. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#validation_error)) |
| `429` | [`rate_limited`](https://tonbo.dev/docs/reference/management.md#rate_limited) | The key or the account sent more requests than its rate allows. | After Retry-After | Wait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#rate_limited)) |

### Retries

- A read: sending it again changes nothing.
- `429` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
curl -sS "https://api.tonbo.dev/v1/usage" \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

## Read the account's spend day by day, or hour by hour

`GET /v1/usage/series` · CLI: `tonbo usage series`

Needs [`usage.read`](https://tonbo.dev/docs/reference/management.md#capability-usage-read), which `owner` and `admin` hold. A narrowed key may not.

The account's rated usage over a window, one point per UTC day (or per hour for `hours`), each split by product and region, from the same charges as `/usage`. Every amount is split by what paid it: `list_micros` is the usage at list price; `allowance_micros` is what the month's free allowance paid; `credit_micros` is what the account's credit balance paid; `outstanding_micros` is still unpaid, which pauses writes; and `charged_micros` is what the usage cost beyond the allowance (`credit_micros` + `outstanding_micros`). A charge counts in the point where its period starts. Billing rates each hour about 15 minutes after it ends, so the current hour, and the current day until then, are still filling in. Every point of the window is listed, with zeros where nothing was used. `month_to_date` is the current UTC month whatever the window. Pass exactly one of `days`, `hours` and `month`; the last 30 days when none is given.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `days` | query | integer | no | The last 1 to 92 UTC days, today included, one point per day. 1 to 92. |
| `hours` | query | integer | no | The last 1 to 48 hours, the current hour included, one point per hour. 1 to 48. |
| `month` | query | string | no | One calendar month in UTC, one point per day. Matches `^[0-9]{4}-(0[1-9]\|1[0-2])$`. |
| `compare` | query | one of `"previous"` | no | `previous` also answers the window just before this one, of the same length (the previous calendar month for `month`), in `previous`. |

### Response

| Status | Answer |
| --- | --- |
| `200` | The spend series |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [UsageSeries](https://tonbo.dev/docs/reference/management/usage.md#schema-usage-series) | yes |  |

| Header | Status | Description |
| --- | --- | --- |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429 | Seconds before the client should retry. |

**Example 200 body**

```json
{
  "data": {
    "start": "2026-11-02T09:30:00.000Z",
    "end": "2026-11-02T09:30:00.000Z",
    "totals": {
      "list_micros": 0,
      "allowance_micros": 0,
      "credit_micros": 0,
      "outstanding_micros": 0,
      "charged_micros": 0
    },
    "points": [
      {
        "list_micros": 0,
        "allowance_micros": 0,
        "credit_micros": 0,
        "outstanding_micros": 0,
        "charged_micros": 0,
        "start": "2026-11-02T09:30:00.000Z",
        "lines": [
          {
            "list_micros": 0,
            "allowance_micros": 0,
            "credit_micros": 0,
            "outstanding_micros": 0,
            "charged_micros": 0,
            "product": "<product>",
            "region": "<region>"
          }
        ]
      }
    ],
    "granularity": "day",
    "currency": "usd",
    "previous": {
      "start": "2026-11-02T09:30:00.000Z",
      "end": "2026-11-02T09:30:00.000Z",
      "totals": {
        "list_micros": 0,
        "allowance_micros": 0,
        "credit_micros": 0,
        "outstanding_micros": 0,
        "charged_micros": 0
      },
      "points": [
        {
          "list_micros": 0,
          "allowance_micros": 0,
          "credit_micros": 0,
          "outstanding_micros": 0,
          "charged_micros": 0,
          "start": "2026-11-02T09:30:00.000Z",
          "lines": [
            {
              "list_micros": 0,
              "allowance_micros": 0,
              "credit_micros": 0,
              "outstanding_micros": 0,
              "charged_micros": 0,
              "product": "<product>",
              "region": "<region>"
            }
          ]
        }
      ]
    },
    "month_to_date": {
      "list_micros": 0,
      "allowance_micros": 0,
      "credit_micros": 0,
      "outstanding_micros": 0,
      "charged_micros": 0,
      "month": "<month>",
      "allowance_granted_micros": 0,
      "projection": {
        "list_micros": 0,
        "charged_micros": 0,
        "basis_days": 3
      }
    }
  }
}
```

### Errors

| Status | Code | When | Send again | What to do |
| --- | --- | --- | --- | --- |
| `401` | [`exchange_required`](https://tonbo.dev/docs/reference/management.md#exchange_required) | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#exchange_required)) |
| `401` | [`unauthenticated`](https://tonbo.dev/docs/reference/management.md#unauthenticated) | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#unauthenticated)) |
| `403` | [`forbidden`](https://tonbo.dev/docs/reference/management.md#forbidden) | The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may. | No | Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#forbidden)) |
| `422` | [`validation_error`](https://tonbo.dev/docs/reference/management.md#validation_error) | A parameter, header or body field breaks its rule; `errors` names each field. | No | Correct the fields `errors` names; the operation’s reference gives each one’s rule. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#validation_error)) |
| `429` | [`rate_limited`](https://tonbo.dev/docs/reference/management.md#rate_limited) | The key or the account sent more requests than its rate allows. | After Retry-After | Wait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#rate_limited)) |

### Retries

- A read: sending it again changes nothing.
- `429` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
curl -sS "https://api.tonbo.dev/v1/usage/series" \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

## Read the account's writes of yesterday and today, hourly

`GET /v1/usage/today` · CLI: `tonbo usage today`

Needs [`usage.read`](https://tonbo.dev/docs/reference/management.md#capability-usage-read), which `owner` and `admin` hold. A narrowed key may not.

The account's Streams writes per UTC hour of yesterday and today, in three lanes: `databases` (its databases, with each Machine's database, logs and inbox), `streams` (its raw streams) and `other` (session processing, a Volume's ledger and usage accounted to a bucket rather than a stream), as the `other` rows of `/usage/databases` and `/usage/streams` hold them; every write is in exactly one lane. Summed over every region the account reaches, with each region's meter checkpoint; a region that cannot be read is named in `unavailable_regions` and left out of the sums. A write counts in the hour that holds its settlement hour, so the current hour grows until it ends; an hour that starts after now answers null. Activity, not money: Usage & billing (`/usage`) shows what is charged.

### Response

| Status | Answer |
| --- | --- |
| `200` | The account's writes of yesterday and today |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [UsageToday](https://tonbo.dev/docs/reference/management/usage.md#schema-usage-today) | yes | The account's writes of yesterday and today, hourly, per lane. |

| Header | Status | Description |
| --- | --- | --- |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429 | Seconds before the client should retry. |

**Example 200 body**

```json
{
  "data": {
    "granularity": "hour",
    "from": "2026-11-02T09:30:00.000Z",
    "to": "2026-11-02T09:30:00.000Z",
    "as_of": "2026-11-02T09:30:00.000Z",
    "regions": [
      {
        "region": "<region>",
        "as_of": "2026-11-02T09:30:00.000Z"
      }
    ],
    "series": {
      "databases": [
        {
          "start": "2026-11-02T09:30:00.000Z",
          "write_units": 0,
          "append_bytes": 0,
          "records": 0
        }
      ],
      "streams": [
        {
          "start": "2026-11-02T09:30:00.000Z",
          "write_units": 0,
          "append_bytes": 0,
          "records": 0
        }
      ],
      "other": [
        {
          "start": "2026-11-02T09:30:00.000Z",
          "write_units": 0,
          "append_bytes": 0,
          "records": 0
        }
      ]
    },
    "unavailable_regions": [
      "<unavailable_regions>"
    ]
  }
}
```

### Errors

| Status | Code | When | Send again | What to do |
| --- | --- | --- | --- | --- |
| `401` | [`exchange_required`](https://tonbo.dev/docs/reference/management.md#exchange_required) | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#exchange_required)) |
| `401` | [`unauthenticated`](https://tonbo.dev/docs/reference/management.md#unauthenticated) | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#unauthenticated)) |
| `403` | [`forbidden`](https://tonbo.dev/docs/reference/management.md#forbidden) | The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may. | No | Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#forbidden)) |
| `429` | [`rate_limited`](https://tonbo.dev/docs/reference/management.md#rate_limited) | The key or the account sent more requests than its rate allows. | After Retry-After | Wait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#rate_limited)) |

### Retries

- A read: sending it again changes nothing.
- `429` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
curl -sS "https://api.tonbo.dev/v1/usage/today" \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

## Read each database's usage of one month at list price

`GET /v1/usage/databases` · CLI: `tonbo database usage`

Needs [`usage.read`](https://tonbo.dev/docs/reference/management.md#capability-usage-read), which `owner` and `admin` hold. A narrowed key may not.

One row per listed database version (name, stream creation time and counting history) metered in the month, rolled up by contracts/streams-databases/v1.json `kinds.values.<kind>.usage`: a Machine's logs and inbox streams are added into its database's row, and a Volume's ledger into `other`; in every region the account reaches, including databases deleted during the month, plus `other` for metered usage outside the account's databases (its streams, which `/usage/streams` lists, session processing and anything unattributed), so the rows and `other` add up to the account's metered total. Values are at list price, before the monthly allowance and credit; Usage & billing (`/usage`) shows what is charged.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `period` | query | string | no | The calendar month in UTC; the current month when omitted. Matches `^[0-9]{4}-(0[1-9]\|1[0-2])$`. |
| `sort` | query | one of `"-list_value"` or `"name"` | no | By list value, highest first (the default), or by name. Default `"-list_value"`. |
| `prefix` | query | string | no | Only databases whose name starts with this prefix. 1 to 85 characters. Matches `^(?!m\.)(?!vol\.)(?!s\.)(?!session\.)(?!proc\.)[a-z0-9][a-z0-9._-]{0,84}$`. |
| `names` | query | string | no | Only these databases, 1 to 100 listed names, comma-separated (a database name or a Machine's database). At least 1 characters. |
| `cursor` | query | string | no | Opaque cursor tied to the original query shape. At least 1 characters. |
| `limit` | query | integer | no | The most items one page holds, 1 to 200; 50 when omitted. A page may hold fewer; read on with `next_cursor` until it is null. Default `50`. 1 to 200. |

### Response

| Status | Answer |
| --- | --- |
| `200` | Per-database usage |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `period` | string | yes | The calendar month counted, in UTC; the `period` asked for, or the current month. Matches `^[0-9]{4}-(0[1-9]\|1[0-2])$`. |
| `as_of` | string (date-time) or null | yes | The oldest meter checkpoint among the regions read; usage after it is not yet counted. Null before a region's first. |
| `currency` | `"usd"` | yes | `usd`: every `_micros` value is in millionths of a US dollar. |
| `basis` | `"at_list_price_before_allowance_and_credit"` | yes | Values are at list price, before the monthly allowance and credit apply; `GET /v1/usage` answers what the account is charged. |
| `pricing` | object | yes | The list prices of contracts/billing/streams-prices-v1.json the values use. |
| `pricing.write_unit_bytes` | integer | yes | The bytes of one write unit. A write counts one unit for each started unit of its bytes, and at least one. |
| `pricing.write_micros_per_million_units` | integer | yes | The price of a million write units, in micro-dollars. |
| `pricing.retention_micros_per_gib_month` | integer | yes | The price of keeping one GiB for one month, in micro-dollars. |
| `pricing.retention_unit_bytes` | integer | yes | The bytes of the GiB that price is quoted for, 1024^3. |
| `pricing.retention_month_seconds` | integer | yes | The seconds of the month that price is quoted for, 30 days. |
| `data` | array of [DatabaseUsage](https://tonbo.dev/docs/reference/management/usage.md#schema-database-usage) | yes | One row per database version metered in the month, in the order `sort` names. |
| `other` | [DatabaseUsageAmounts](https://tonbo.dev/docs/reference/management/usage.md#schema-database-usage-amounts) | yes | Metered usage outside the account's databases (its streams, session processing and anything unattributed), in every region read. |
| `next_cursor` | string or null | yes | The `cursor` of the next page, sent with the same other parameters; null on the last page. |
| `unavailable_regions` | array of string | yes | Regions whose usage could not be read; their databases and `other` are missing from this answer. |

| Header | Status | Description |
| --- | --- | --- |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429 | Seconds before the client should retry. |

**Example 200 body**

```json
{
  "period": "2026-11",
  "as_of": "2026-11-02T09:30:00.000Z",
  "currency": "usd",
  "basis": "at_list_price_before_allowance_and_credit",
  "pricing": {
    "write_unit_bytes": 1,
    "write_micros_per_million_units": 1,
    "retention_micros_per_gib_month": 1,
    "retention_unit_bytes": 1,
    "retention_month_seconds": 1
  },
  "data": [
    {
      "write_units": "<write_units>",
      "retention_gib_months": "<retention_gib_months>",
      "snapshot_gib_months": "<snapshot_gib_months>",
      "list_value_micros": 0,
      "name": "<name>",
      "kind": "database",
      "owner_id": "3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f",
      "region": "<region>",
      "stream_created_at": "2026-11-02T09:30:00.000Z",
      "counted_since": "<counted_since>",
      "state": "active",
      "created_at": "2026-11-02T09:30:00.000Z",
      "deleted_at": "2026-11-02T09:30:00.000Z"
    }
  ],
  "other": {
    "write_units": "<write_units>",
    "retention_gib_months": "<retention_gib_months>",
    "snapshot_gib_months": "<snapshot_gib_months>",
    "list_value_micros": 0
  },
  "next_cursor": "<next_cursor>",
  "unavailable_regions": [
    "<unavailable_regions>"
  ]
}
```

### Errors

| Status | Code | When | Send again | What to do |
| --- | --- | --- | --- | --- |
| `401` | [`exchange_required`](https://tonbo.dev/docs/reference/management.md#exchange_required) | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#exchange_required)) |
| `401` | [`unauthenticated`](https://tonbo.dev/docs/reference/management.md#unauthenticated) | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#unauthenticated)) |
| `403` | [`forbidden`](https://tonbo.dev/docs/reference/management.md#forbidden) | The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may. | No | Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#forbidden)) |
| `422` | [`validation_error`](https://tonbo.dev/docs/reference/management.md#validation_error) | A parameter, header or body field breaks its rule; `errors` names each field. | No | Correct the fields `errors` names; the operation’s reference gives each one’s rule. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#validation_error)) |
| `429` | [`rate_limited`](https://tonbo.dev/docs/reference/management.md#rate_limited) | The key or the account sent more requests than its rate allows. | After Retry-After | Wait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#rate_limited)) |

### Retries

- A read: sending it again changes nothing.
- `429` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
curl -sS "https://api.tonbo.dev/v1/usage/databases" \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

## Read each stream's usage of one month at list price

`GET /v1/usage/streams` · CLI: `tonbo stream usage`

Needs [`usage.read`](https://tonbo.dev/docs/reference/management.md#capability-usage-read), which `owner` and `admin` hold. A narrowed key may not.

One row per stream version (name, stream creation time and counting history) metered in the month, in every region the account reaches, including streams deleted during the month, plus `other` for metered usage outside the account's streams (its databases, session processing and anything unattributed), so the rows and `other` add up to the account's metered total, as `/usage/databases` does for databases; no stream is a row of both. Values are at list price, before the monthly allowance and credit, which databases and streams share; Usage & billing (`/usage`) shows what is charged.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `period` | query | string | no | The calendar month in UTC; the current month when omitted. Matches `^[0-9]{4}-(0[1-9]\|1[0-2])$`. |
| `sort` | query | one of `"-list_value"` or `"name"` | no | By list value, highest first (the default), or by name. Default `"-list_value"`. |
| `prefix` | query | string | no | Only streams whose name starts with this prefix. 1 to 85 characters. Matches `^(?!m\.)(?!vol\.)(?!s\.)(?!session\.)(?!proc\.)[a-z0-9][a-z0-9._-]{0,84}$`. |
| `names` | query | string | no | Only these streams, 1 to 100 stream names, comma-separated. At least 1 characters. |
| `cursor` | query | string | no | Opaque cursor tied to the original query shape. At least 1 characters. |
| `limit` | query | integer | no | The most items one page holds, 1 to 200; 50 when omitted. A page may hold fewer; read on with `next_cursor` until it is null. Default `50`. 1 to 200. |

### Response

| Status | Answer |
| --- | --- |
| `200` | Per-stream usage |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `period` | string | yes | The calendar month counted, in UTC; the `period` asked for, or the current month. Matches `^[0-9]{4}-(0[1-9]\|1[0-2])$`. |
| `as_of` | string (date-time) or null | yes | The oldest meter checkpoint among the regions read; usage after it is not yet counted. Null before a region's first. |
| `currency` | `"usd"` | yes | `usd`: every `_micros` value is in millionths of a US dollar. |
| `basis` | `"at_list_price_before_allowance_and_credit"` | yes | Values are at list price, before the monthly allowance and credit apply; `GET /v1/usage` answers what the account is charged. |
| `pricing` | object | yes | The list prices of contracts/billing/streams-prices-v1.json the values use. |
| `pricing.write_unit_bytes` | integer | yes | The bytes of one write unit. A write counts one unit for each started unit of its bytes, and at least one. |
| `pricing.write_micros_per_million_units` | integer | yes | The price of a million write units, in micro-dollars. |
| `pricing.retention_micros_per_gib_month` | integer | yes | The price of keeping one GiB for one month, in micro-dollars. |
| `pricing.retention_unit_bytes` | integer | yes | The bytes of the GiB that price is quoted for, 1024^3. |
| `pricing.retention_month_seconds` | integer | yes | The seconds of the month that price is quoted for, 30 days. |
| `data` | array of [StreamUsage](https://tonbo.dev/docs/reference/management/usage.md#schema-stream-usage) | yes | One row per stream version metered in the month, in the order `sort` names. |
| `other` | [DatabaseUsageAmounts](https://tonbo.dev/docs/reference/management/usage.md#schema-database-usage-amounts) | yes | Metered usage outside the account's streams (its databases, session processing and anything unattributed), in every region read. |
| `next_cursor` | string or null | yes | The `cursor` of the next page, sent with the same other parameters; null on the last page. |
| `unavailable_regions` | array of string | yes | Regions whose usage could not be read; their streams and `other` are missing from this answer. |

| Header | Status | Description |
| --- | --- | --- |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429 | Seconds before the client should retry. |

**Example 200 body**

```json
{
  "period": "2026-11",
  "as_of": "2026-11-02T09:30:00.000Z",
  "currency": "usd",
  "basis": "at_list_price_before_allowance_and_credit",
  "pricing": {
    "write_unit_bytes": 1,
    "write_micros_per_million_units": 1,
    "retention_micros_per_gib_month": 1,
    "retention_unit_bytes": 1,
    "retention_month_seconds": 1
  },
  "data": [
    {
      "write_units": "<write_units>",
      "retention_gib_months": "<retention_gib_months>",
      "snapshot_gib_months": "<snapshot_gib_months>",
      "list_value_micros": 0,
      "name": "<name>",
      "region": "<region>",
      "stream_created_at": "2026-11-02T09:30:00.000Z",
      "counted_since": "<counted_since>",
      "state": "active",
      "created_at": "2026-11-02T09:30:00.000Z",
      "deleted_at": "2026-11-02T09:30:00.000Z"
    }
  ],
  "other": {
    "write_units": "<write_units>",
    "retention_gib_months": "<retention_gib_months>",
    "snapshot_gib_months": "<snapshot_gib_months>",
    "list_value_micros": 0
  },
  "next_cursor": "<next_cursor>",
  "unavailable_regions": [
    "<unavailable_regions>"
  ]
}
```

### Errors

| Status | Code | When | Send again | What to do |
| --- | --- | --- | --- | --- |
| `401` | [`exchange_required`](https://tonbo.dev/docs/reference/management.md#exchange_required) | The key acts as an Agent, and an Agent’s key is never sent itself. | No | Exchange the key for a token at the endpoint the answer’s `token_endpoint` names, and send the token as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#exchange_required)) |
| `401` | [`unauthenticated`](https://tonbo.dev/docs/reference/management.md#unauthenticated) | The request carries no key or token, or one that is invalid, expired or revoked. | No | Send a valid key, or a token that has not expired, as `Authorization: Bearer`. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#unauthenticated)) |
| `403` | [`forbidden`](https://tonbo.dev/docs/reference/management.md#forbidden) | The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may. | No | Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#forbidden)) |
| `422` | [`validation_error`](https://tonbo.dev/docs/reference/management.md#validation_error) | A parameter, header or body field breaks its rule; `errors` names each field. | No | Correct the fields `errors` names; the operation’s reference gives each one’s rule. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#validation_error)) |
| `429` | [`rate_limited`](https://tonbo.dev/docs/reference/management.md#rate_limited) | The key or the account sent more requests than its rate allows. | After Retry-After | Wait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#rate_limited)) |

### Retries

- A read: sending it again changes nothing.
- `429` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
curl -sS "https://api.tonbo.dev/v1/usage/streams" \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

## Objects

### DatabaseUsage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `write_units` | string | yes | Write units, an integer as text. Matches `^(0\|[1-9][0-9]*)$`. |
| `retention_gib_months` | string | yes | The retained log in GiB-months (GiB = 1024^3 bytes, month = retention_month_seconds), a decimal as text. |
| `snapshot_gib_months` | string or null | yes | Snapshots in GiB-months, a decimal as text; null when never reported. |
| `list_value_micros` | integer | yes | The value at list price in micro-dollars, before allowance and credit. At least 0. |
| `name` | string or string | yes | The database's name; a Machine's database is `m.<machine id>`. |
| `kind` | one of `"database"` or `"machine"` | yes | `database` for one a member created, `machine` for a Machine's own. |
| `owner_id` | string (uuid) or null | yes | The Machine that owns a `machine` row, whose logs and inbox streams are added into it; null for a member's database. |
| `region` | string | yes | The database's region. Matches `^[a-z]{2}-[a-z]+-[0-9]$`. |
| `stream_created_at` | string (date-time) | yes | When Ursula created the stream version; with `counted_since`, the version the row is. |
| `counted_since` | string | yes | The Ursula usage history the version began counting in, 16 hex digits. Matches `^[0-9a-f]{16}$`. |
| `state` | one of `"active"` or `"deleted"` | yes | `active` while this version of the database exists, `deleted` once it was deleted; a deleted version's usage in the month still counts. |
| `created_at` | string (date-time) or null | yes | Null for a metered version the registry does not know. |
| `deleted_at` | string (date-time) or null | yes | When this version was deleted; null while it is active. |

**Example DatabaseUsage**

```json
{
  "write_units": "<write_units>",
  "retention_gib_months": "<retention_gib_months>",
  "snapshot_gib_months": "<snapshot_gib_months>",
  "list_value_micros": 0,
  "name": "<name>",
  "kind": "database",
  "owner_id": "3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f",
  "region": "<region>",
  "stream_created_at": "2026-11-02T09:30:00.000Z",
  "counted_since": "<counted_since>",
  "state": "active",
  "created_at": "2026-11-02T09:30:00.000Z",
  "deleted_at": "2026-11-02T09:30:00.000Z"
}
```

### DatabaseUsageAmounts

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `write_units` | string | yes | Write units, an integer as text. Matches `^(0\|[1-9][0-9]*)$`. |
| `retention_gib_months` | string | yes | The retained log in GiB-months (GiB = 1024^3 bytes, month = retention_month_seconds), a decimal as text. |
| `snapshot_gib_months` | string or null | yes | Snapshots in GiB-months, a decimal as text; null when never reported. |
| `list_value_micros` | integer | yes | The value at list price in micro-dollars, before allowance and credit. At least 0. |

**Example DatabaseUsageAmounts**

```json
{
  "write_units": "<write_units>",
  "retention_gib_months": "<retention_gib_months>",
  "snapshot_gib_months": "<snapshot_gib_months>",
  "list_value_micros": 0
}
```

### SpendAmounts

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `list_micros` | integer | yes | The usage at list price, in micro-dollars; the sum of the other three amounts besides `charged_micros`. At least 0. |
| `allowance_micros` | integer | yes | What the month's free allowance paid. At least 0. |
| `credit_micros` | integer | yes | What the account's credit balance paid. At least 0. |
| `outstanding_micros` | integer | yes | What is still unpaid; writes pause while the account owes it. At least 0. |
| `charged_micros` | integer | yes | What the usage cost beyond the allowance, `credit_micros` + `outstanding_micros`. At least 0. |

**Example SpendAmounts**

```json
{
  "list_micros": 0,
  "allowance_micros": 0,
  "credit_micros": 0,
  "outstanding_micros": 0,
  "charged_micros": 0
}
```

### StreamUsage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `write_units` | string | yes | Write units, an integer as text. Matches `^(0\|[1-9][0-9]*)$`. |
| `retention_gib_months` | string | yes | The retained log in GiB-months (GiB = 1024^3 bytes, month = retention_month_seconds), a decimal as text. |
| `snapshot_gib_months` | string or null | yes | Snapshots in GiB-months, a decimal as text; null when never reported. |
| `list_value_micros` | integer | yes | The value at list price in micro-dollars, before allowance and credit. At least 0. |
| `name` | string | yes | The stream's name, without `s.`. 1 to 83 characters. Matches `^(?!m\.)(?!vol\.)(?!s\.)(?!session\.)(?!proc\.)(?!(?:streams\|new)$)(?!.*\.\.)[a-z0-9](?:[a-z0-9._-]{0,81}[a-z0-9])?$`. |
| `region` | string | yes | The stream's region. Matches `^[a-z]{2}-[a-z]+-[0-9]$`. |
| `stream_created_at` | string (date-time) | yes | When Ursula created the stream version; with `counted_since`, the version the row is. |
| `counted_since` | string | yes | The Ursula usage history the version began counting in, 16 hex digits. Matches `^[0-9a-f]{16}$`. |
| `state` | one of `"active"` or `"deleted"` | yes | `active` while this version of the stream exists, `deleted` once it was deleted; a deleted version's usage in the month still counts. |
| `created_at` | string (date-time) or null | yes | Null for a metered version the registry does not know. |
| `deleted_at` | string (date-time) or null | yes | When this version was deleted; null while it is active. |

**Example StreamUsage**

```json
{
  "write_units": "<write_units>",
  "retention_gib_months": "<retention_gib_months>",
  "snapshot_gib_months": "<snapshot_gib_months>",
  "list_value_micros": 0,
  "name": "<name>",
  "region": "<region>",
  "stream_created_at": "2026-11-02T09:30:00.000Z",
  "counted_since": "<counted_since>",
  "state": "active",
  "created_at": "2026-11-02T09:30:00.000Z",
  "deleted_at": "2026-11-02T09:30:00.000Z"
}
```

### Usage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `period` | string | yes | The calendar month counted, in UTC; the `period` asked for, or the current month. Matches `^[0-9]{4}-(0[1-9]\|1[0-2])$`. |
| `currency` | `"usd"` | yes | `usd`: every `_micros` amount is in millionths of a US dollar. |
| `total_micros` | integer | yes | The month's total, the sum of every line's `amount_micros`. |
| `lines` | array of object | yes | One line for each product, region, dimension and model charged in the month, in that order. |
| `lines[].product` | string | yes | The product charged, such as `streams` for databases and streams, or `machines`. |
| `lines[].region` | string | yes | The region the usage was in. |
| `lines[].dimension` | string | yes | What was measured, such as `write_units` or `retention_byte_seconds`. |
| `lines[].model` | string or null | yes | The model the line was priced for, for a product priced by model; null otherwise. |
| `lines[].quantity` | string | yes | Decimal quantity, as text. |
| `lines[].amount_micros` | integer | yes | The line's charge, in micro-dollars. |

**Example Usage**

```json
{
  "period": "2026-11",
  "currency": "usd",
  "total_micros": 1,
  "lines": [
    {
      "product": "<product>",
      "region": "<region>",
      "dimension": "<dimension>",
      "model": "<model>",
      "quantity": "<quantity>",
      "amount_micros": 1
    }
  ]
}
```

### UsageSeries

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | string (date-time) | yes | The window's first instant, the start of its first point. |
| `end` | string (date-time) | yes | The instant the window ends, exclusive; the end of its last point. |
| `totals` | [SpendAmounts](https://tonbo.dev/docs/reference/management/usage.md#schema-spend-amounts) | yes | The window's amounts, the sums of its points. |
| `points` | array of any | yes | Every day (or hour) of the window, oldest first. |
| `points[].list_micros` | integer | yes | The usage at list price, in micro-dollars; the sum of the other three amounts besides `charged_micros`. At least 0. |
| `points[].allowance_micros` | integer | yes | What the month's free allowance paid. At least 0. |
| `points[].credit_micros` | integer | yes | What the account's credit balance paid. At least 0. |
| `points[].outstanding_micros` | integer | yes | What is still unpaid; writes pause while the account owes it. At least 0. |
| `points[].charged_micros` | integer | yes | What the usage cost beyond the allowance, `credit_micros` + `outstanding_micros`. At least 0. |
| `points[].start` | string (date-time) | yes | The point's first instant, a UTC midnight for a day. |
| `points[].lines` | array of any | yes | The point's amounts for each product and region used in it, in that order; empty when nothing was used. |
| `points[].lines[].list_micros` | integer | yes | The usage at list price, in micro-dollars; the sum of the other three amounts besides `charged_micros`. At least 0. |
| `points[].lines[].allowance_micros` | integer | yes | What the month's free allowance paid. At least 0. |
| `points[].lines[].credit_micros` | integer | yes | What the account's credit balance paid. At least 0. |
| `points[].lines[].outstanding_micros` | integer | yes | What is still unpaid; writes pause while the account owes it. At least 0. |
| `points[].lines[].charged_micros` | integer | yes | What the usage cost beyond the allowance, `credit_micros` + `outstanding_micros`. At least 0. |
| `points[].lines[].product` | string | yes | The product charged, such as `streams` for databases and streams, or `machines`. |
| `points[].lines[].region` | string or null | yes | The region the usage was in; null for a charge per call, such as a Machine's, which names none. |
| `granularity` | one of `"day"` or `"hour"` | yes | `day` for `days` and `month`, `hour` for `hours`. |
| `currency` | `"usd"` | yes | `usd`: every `_micros` amount is in millionths of a US dollar. |
| `previous` | [UsageSeriesWindow](https://tonbo.dev/docs/reference/management/usage.md#schema-usage-series-window) or null | yes | The window just before this one, with `compare=previous`; null otherwise. |
| `previous.start` | string (date-time) | yes | The window's first instant, the start of its first point. |
| `previous.end` | string (date-time) | yes | The instant the window ends, exclusive; the end of its last point. |
| `previous.totals` | [SpendAmounts](https://tonbo.dev/docs/reference/management/usage.md#schema-spend-amounts) | yes | The window's amounts, the sums of its points. |
| `previous.points` | array of any | yes | Every day (or hour) of the window, oldest first. |
| `previous.points[].list_micros` | integer | yes | The usage at list price, in micro-dollars; the sum of the other three amounts besides `charged_micros`. At least 0. |
| `previous.points[].allowance_micros` | integer | yes | What the month's free allowance paid. At least 0. |
| `previous.points[].credit_micros` | integer | yes | What the account's credit balance paid. At least 0. |
| `previous.points[].outstanding_micros` | integer | yes | What is still unpaid; writes pause while the account owes it. At least 0. |
| `previous.points[].charged_micros` | integer | yes | What the usage cost beyond the allowance, `credit_micros` + `outstanding_micros`. At least 0. |
| `previous.points[].start` | string (date-time) | yes | The point's first instant, a UTC midnight for a day. |
| `previous.points[].lines` | array of any | yes | The point's amounts for each product and region used in it, in that order; empty when nothing was used. |
| `previous.points[].lines[].list_micros` | integer | yes | The usage at list price, in micro-dollars; the sum of the other three amounts besides `charged_micros`. At least 0. |
| `previous.points[].lines[].allowance_micros` | integer | yes | What the month's free allowance paid. At least 0. |
| `previous.points[].lines[].credit_micros` | integer | yes | What the account's credit balance paid. At least 0. |
| `previous.points[].lines[].outstanding_micros` | integer | yes | What is still unpaid; writes pause while the account owes it. At least 0. |
| `previous.points[].lines[].charged_micros` | integer | yes | What the usage cost beyond the allowance, `credit_micros` + `outstanding_micros`. At least 0. |
| `previous.points[].lines[].product` | string | yes | The product charged, such as `streams` for databases and streams, or `machines`. |
| `previous.points[].lines[].region` | string or null | yes | The region the usage was in; null for a charge per call, such as a Machine's, which names none. |
| `month_to_date` | any | yes | The current UTC month so far. |
| `month_to_date.list_micros` | integer | yes | The usage at list price, in micro-dollars; the sum of the other three amounts besides `charged_micros`. At least 0. |
| `month_to_date.allowance_micros` | integer | yes | What the month's free allowance paid. At least 0. |
| `month_to_date.credit_micros` | integer | yes | What the account's credit balance paid. At least 0. |
| `month_to_date.outstanding_micros` | integer | yes | What is still unpaid; writes pause while the account owes it. At least 0. |
| `month_to_date.charged_micros` | integer | yes | What the usage cost beyond the allowance, `credit_micros` + `outstanding_micros`. At least 0. |
| `month_to_date.month` | string | yes | The current calendar month in UTC. Matches `^[0-9]{4}-(0[1-9]\|1[0-2])$`. |
| `month_to_date.allowance_granted_micros` | integer | yes | The free allowance the account was granted for the month; 0 for an account that gets none. At least 0. |
| `month_to_date.projection` | object or null | yes | The month's spend if it continues at the average of its complete UTC days so far: the list amount of those days, divided by their number and multiplied by the month's days. `charged_micros` is that amount less the month's allowance, never below zero. It is a run rate, not a forecast, and null until three days of the month are complete. |
| `month_to_date.projection.list_micros` | integer | yes | The projected usage at list price. At least 0. |
| `month_to_date.projection.charged_micros` | integer | yes | The projected cost beyond the allowance. At least 0. |
| `month_to_date.projection.basis_days` | integer | yes | The complete days the run rate is taken from. At least 3. |

**Example UsageSeries**

```json
{
  "start": "2026-11-02T09:30:00.000Z",
  "end": "2026-11-02T09:30:00.000Z",
  "totals": {
    "list_micros": 0,
    "allowance_micros": 0,
    "credit_micros": 0,
    "outstanding_micros": 0,
    "charged_micros": 0
  },
  "points": [
    {
      "list_micros": 0,
      "allowance_micros": 0,
      "credit_micros": 0,
      "outstanding_micros": 0,
      "charged_micros": 0,
      "start": "2026-11-02T09:30:00.000Z",
      "lines": [
        {
          "list_micros": 0,
          "allowance_micros": 0,
          "credit_micros": 0,
          "outstanding_micros": 0,
          "charged_micros": 0,
          "product": "<product>",
          "region": "<region>"
        }
      ]
    }
  ],
  "granularity": "day",
  "currency": "usd",
  "previous": {
    "start": "2026-11-02T09:30:00.000Z",
    "end": "2026-11-02T09:30:00.000Z",
    "totals": {
      "list_micros": 0,
      "allowance_micros": 0,
      "credit_micros": 0,
      "outstanding_micros": 0,
      "charged_micros": 0
    },
    "points": [
      {
        "list_micros": 0,
        "allowance_micros": 0,
        "credit_micros": 0,
        "outstanding_micros": 0,
        "charged_micros": 0,
        "start": "2026-11-02T09:30:00.000Z",
        "lines": [
          {
            "list_micros": 0,
            "allowance_micros": 0,
            "credit_micros": 0,
            "outstanding_micros": 0,
            "charged_micros": 0,
            "product": "<product>",
            "region": "<region>"
          }
        ]
      }
    ]
  },
  "month_to_date": {
    "list_micros": 0,
    "allowance_micros": 0,
    "credit_micros": 0,
    "outstanding_micros": 0,
    "charged_micros": 0,
    "month": "<month>",
    "allowance_granted_micros": 0,
    "projection": {
      "list_micros": 0,
      "charged_micros": 0,
      "basis_days": 3
    }
  }
}
```

### UsageSeriesWindow

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | string (date-time) | yes | The window's first instant, the start of its first point. |
| `end` | string (date-time) | yes | The instant the window ends, exclusive; the end of its last point. |
| `totals` | [SpendAmounts](https://tonbo.dev/docs/reference/management/usage.md#schema-spend-amounts) | yes | The window's amounts, the sums of its points. |
| `points` | array of any | yes | Every day (or hour) of the window, oldest first. |
| `points[].list_micros` | integer | yes | The usage at list price, in micro-dollars; the sum of the other three amounts besides `charged_micros`. At least 0. |
| `points[].allowance_micros` | integer | yes | What the month's free allowance paid. At least 0. |
| `points[].credit_micros` | integer | yes | What the account's credit balance paid. At least 0. |
| `points[].outstanding_micros` | integer | yes | What is still unpaid; writes pause while the account owes it. At least 0. |
| `points[].charged_micros` | integer | yes | What the usage cost beyond the allowance, `credit_micros` + `outstanding_micros`. At least 0. |
| `points[].start` | string (date-time) | yes | The point's first instant, a UTC midnight for a day. |
| `points[].lines` | array of any | yes | The point's amounts for each product and region used in it, in that order; empty when nothing was used. |
| `points[].lines[].list_micros` | integer | yes | The usage at list price, in micro-dollars; the sum of the other three amounts besides `charged_micros`. At least 0. |
| `points[].lines[].allowance_micros` | integer | yes | What the month's free allowance paid. At least 0. |
| `points[].lines[].credit_micros` | integer | yes | What the account's credit balance paid. At least 0. |
| `points[].lines[].outstanding_micros` | integer | yes | What is still unpaid; writes pause while the account owes it. At least 0. |
| `points[].lines[].charged_micros` | integer | yes | What the usage cost beyond the allowance, `credit_micros` + `outstanding_micros`. At least 0. |
| `points[].lines[].product` | string | yes | The product charged, such as `streams` for databases and streams, or `machines`. |
| `points[].lines[].region` | string or null | yes | The region the usage was in; null for a charge per call, such as a Machine's, which names none. |

**Example UsageSeriesWindow**

```json
{
  "start": "2026-11-02T09:30:00.000Z",
  "end": "2026-11-02T09:30:00.000Z",
  "totals": {
    "list_micros": 0,
    "allowance_micros": 0,
    "credit_micros": 0,
    "outstanding_micros": 0,
    "charged_micros": 0
  },
  "points": [
    {
      "list_micros": 0,
      "allowance_micros": 0,
      "credit_micros": 0,
      "outstanding_micros": 0,
      "charged_micros": 0,
      "start": "2026-11-02T09:30:00.000Z",
      "lines": [
        {
          "list_micros": 0,
          "allowance_micros": 0,
          "credit_micros": 0,
          "outstanding_micros": 0,
          "charged_micros": 0,
          "product": "<product>",
          "region": "<region>"
        }
      ]
    }
  ]
}
```

### UsageToday

The account's writes of yesterday and today, hourly, per lane.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `granularity` | one of `"hour"` | yes | One point per UTC hour. |
| `from` | string (date-time) | yes | Yesterday's start, UTC. |
| `to` | string (date-time) | yes | Tomorrow's start, UTC (exclusive). |
| `as_of` | string (date-time) or null | yes | The oldest checkpoint of the regions read; null when one of them has none or no region was read. |
| `regions` | array of object | yes | Each region read, by id, with its meter's checkpoint. |
| `regions[].region` | string | yes | The region. Matches `^[a-z]{2}-[a-z]+-[0-9]$`. |
| `regions[].as_of` | string (date-time) or null | yes | When its meter last completed a poll; null when it has never completed one. |
| `series` | object | yes | The writes of each lane, 48 hourly points each, oldest first. |
| `series.databases` | array of [WritePoint](https://tonbo.dev/docs/reference/management/usage.md#schema-write-point) | yes | The account's databases, with each Machine's database, logs and inbox. |
| `series.streams` | array of [WritePoint](https://tonbo.dev/docs/reference/management/usage.md#schema-write-point) | yes | The account's raw streams. |
| `series.other` | array of [WritePoint](https://tonbo.dev/docs/reference/management/usage.md#schema-write-point) | yes | Everything else metered for the account (session processing, a Volume's ledger, usage accounted to a bucket rather than a stream). |
| `unavailable_regions` | array of string | yes | Regions of the account that could not be read, left out of the sums. |

**Example UsageToday**

```json
{
  "granularity": "hour",
  "from": "2026-11-02T09:30:00.000Z",
  "to": "2026-11-02T09:30:00.000Z",
  "as_of": "2026-11-02T09:30:00.000Z",
  "regions": [
    {
      "region": "<region>",
      "as_of": "2026-11-02T09:30:00.000Z"
    }
  ],
  "series": {
    "databases": [
      {
        "start": "2026-11-02T09:30:00.000Z",
        "write_units": 0,
        "append_bytes": 0,
        "records": 0
      }
    ],
    "streams": [
      {
        "start": "2026-11-02T09:30:00.000Z",
        "write_units": 0,
        "append_bytes": 0,
        "records": 0
      }
    ],
    "other": [
      {
        "start": "2026-11-02T09:30:00.000Z",
        "write_units": 0,
        "append_bytes": 0,
        "records": 0
      }
    ]
  },
  "unavailable_regions": [
    "<unavailable_regions>"
  ]
}
```

### WritePoint

One step of a write series.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | string (date-time) | yes | The step's start, on its UTC hour or day. |
| `write_units` | integer or null | yes | Write units committed in the step (contracts/billing/streams-prices-v1.json `write_unit_bytes` each); null for a step that starts after now. At least 0. |
| `append_bytes` | integer or null | yes | Bytes appended in the step; null for a step that starts after now. At least 0. |
| `records` | integer or null | yes | Records appended in the step; null for a step that starts after now. At least 0. |

**Example WritePoint**

```json
{
  "start": "2026-11-02T09:30:00.000Z",
  "write_units": 0,
  "append_bytes": 0,
  "records": 0
}
```