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

# Management API: Volumes

Last updated 3 November 2026

The account's Volumes (contracts/machines/volume-v1.json): disks in one region, each bound to at most one Machine of that region through the Machine's `volumes`. [The overview](https://tonbo.dev/docs/reference/management.md) covers what every operation shares: authentication, roles, errors, pagination, idempotency and If-Match.

- [`GET /volumes`](#list-volumes) List the account's Volumes
- [`POST /volumes`](#create-volume) Create a Volume
- [`GET /volumes/{name}`](#get-volume) Read a Volume
- [`DELETE /volumes/{name}`](#delete-volume) Delete a Volume
- [`GET /volumes/{name}/metrics`](#get-volume-name-metrics) Read a Volume's metrics over a window
- [Objects](#objects): [Volume](#schema-volume) and [VolumeNameMetrics](#schema-volume-name-metrics)

## List the account's Volumes {#list-volumes}

`GET /v1/volumes` · CLI: `tonbo volume list`

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

The account's Volumes (contracts/machines/volume-v1.json) from every region, by name, including those being deleted until their purge ends; `unavailable_regions` names the regions whose Volumes could not be read. An account holds at most `quotas.volumes_per_account` Volumes, so the list is not paged. Served whatever `machines.open` says; a narrowed key never reaches a Volume.

### Response {#list-volumes-response}

| Status | Answer |
| --- | --- |
| `200` | Volumes |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of [Volume](https://tonbo.dev/docs/reference/management/volumes.md#schema-volume) | yes | The account's Volumes in every region it could read, by name. |
| `unavailable_regions` | array of string | yes | The regions whose Volumes could not be read; their Volumes are missing from `data`. |

| 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": [
    {
      "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
      "name": "data",
      "region": "xx-example-1",
      "size_gib": 20,
      "machine": null,
      "state": "available",
      "live_bytes": 0,
      "last_commit_at": null,
      "created_at": "2027-02-15T09:30:00Z",
      "writes_held": null
    }
  ],
  "unavailable_regions": [
    "<unavailable_regions>"
  ]
}
```

### Errors {#list-volumes-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 {#list-volumes-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/volumes" \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

## Create a Volume {#create-volume}

`POST /v1/volumes` · CLI: `tonbo volume create`

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

A Volume in `region`, created `available`, of `size_gib` (1 to 100, fixed for its life). `size_gib` may be left out (contracts/machines/volume-v1.json `size`): in a region whose new Volumes take the account's size, the Volume is then the account's current total (contracts/billing/account-unlocks-v1.json `volumes`), at most 100 GiB; elsewhere it is 10 GiB. An account that has never bought credit holds one Volume, in any region, of at most its total (contracts/billing/account-unlocks-v1.json `volumes`): a second create answers 402 `payment_required`, and a size past the total the same naming `size_gib`; Volumes it already holds past one keep working. A Machine of the same region binds it through its spec `volumes`. It needs `machines.write`, a region where Machines are offered to the account (422 `region_not_offered` otherwise) and the account's Volumes there (contracts/machines/volume-v1.json `flag`, the same 422 otherwise). An account whose credit is exhausted answers 402 `payment_required` and nothing is written. A name another live Volume of the account holds, in any region, answers 409 `conflict`, and so does a Volume past the account's `quotas.volumes_per_account`. `for_machine` names the Machine the Volume is made for, as the console's create form does for the disk it makes, which then deletes it by default when that Machine is deleted (contracts/machines/machine-v2.json `delete_volume`); a replay must name the same one. The answer is 201 with the new Volume, and 200 when the same Idempotency-Key replays it; the key reused for another request answers 409. Both carry `Location`, the Volume's URL. Billing counts the Volume's live bytes, never its size.

### Parameters {#create-volume-parameters}

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | yes | A value you choose for this one creation, 1 to 255 characters, such as a new UUID. Send a new one for each resource you create, and the same one only to retry that request after a timeout or a lost answer: the retry answers what the first request created, in its current state, and never creates a second. A key reused for a different database, stream or Machine answers 409. 1 to 255 characters. |

### Request body {#create-volume-body}

`application/json`, required. Unknown fields are refused.

The fields below are the contract’s, with their types and limits; [Things to know](https://tonbo.dev/docs/machines/volumes/things-to-know.md) explains what each one does.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | 1 to 40 characters. Matches `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`. Never `"self"`. |
| `region` | string | yes | Matches `^[a-z]{2}(-gov)?-[a-z]+-[0-9]+$`. |
| `size_gib` | integer | no | 1 to 100. |
| `for_machine` | string | no | 1 to 40 characters. Matches `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`. Never `"self"`. |

### Response {#create-volume-response}

| Status | Answer |
| --- | --- |
| `200` | The Volume an earlier request with this Idempotency-Key created |
| `201` | The new Volume |

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

| Header | Status | Description |
| --- | --- | --- |
| `Location` | 200, 201 | The Volume's URL, `https://api.tonbo.dev/v1/volumes/{name}`. |
| `WWW-Authenticate` | 401 | Authentication scheme required by this API. |
| `Retry-After` | 429, 503 | Seconds before the client should retry. |

**Example 200 body**

```json
{
  "data": {
    "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
    "name": "data",
    "region": "xx-example-1",
    "size_gib": 20,
    "machine": null,
    "state": "available",
    "live_bytes": 0,
    "last_commit_at": null,
    "created_at": "2027-02-15T09:30:00Z",
    "writes_held": null
  }
}
```

### Errors {#create-volume-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)) |
| `402` | [`payment_required`](https://tonbo.dev/docs/reference/management.md#payment_required) | The account’s balance is zero, so nothing new is created. Also, before an account has paid (contracts/billing/account-unlocks-v1.json): a request that makes a Machine port public on an account with neither a card nor bought credit (`errors` names `ports`), and a Volume create by an account that has never bought credit that already holds a Volume in any region (`volumes.never_paid_max_count`, one), or of a Volume larger than its total, `volumes.never_paid_total_gib` without a card and `volumes.card_bound_total_gib` with one (`size_gib`). | No | Add credit on Usage & billing, which lifts all of them. Or add a card there (adding one charges nothing) for a public port or a larger Volume; then send the request again. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#payment_required)) |
| `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)) |
| `409` | [`conflict`](https://tonbo.dev/docs/reference/management.md#conflict) | The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. `detail` says which, and `errors` names the field. | No | Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#conflict)) |
| `409` | [`idempotency_conflict`](https://tonbo.dev/docs/reference/management.md#idempotency_conflict) | The Idempotency-Key was already sent with a different request. | No | Send the request with a new Idempotency-Key, or send the request the key was first used for. ([more](https://tonbo.dev/docs/machines/troubleshooting/manage.md#idempotency_conflict)) |
| `422` | [`region_not_offered`](https://tonbo.dev/docs/reference/management.md#region_not_offered) | The resource is not offered in the region named, or in the account’s default region. Nothing was written. | No | Name a region where it is offered; `GET /v1/regions` lists the regions and what each offers. ([more](https://tonbo.dev/docs/machines/troubleshooting/manage.md#region_not_offered)) |
| `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)) |
| `503` | [`region_unavailable`](https://tonbo.dev/docs/reference/management.md#region_unavailable) | The region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After. | After Retry-After | Send the request again after Retry-After; if `detail` says the region takes no new resource of this kind, name another region. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#region_unavailable)) |

### Retries {#create-volume-retries}

- Send a new [`Idempotency-Key`](#create-volume-header-idempotency-key) with each request and the same one when you send it again: a repeat answers what the first request did, and the key reused for a different request answers 409 (see [Idempotency](https://tonbo.dev/docs/reference/management.md#idempotency)).
- `429` and `503` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
curl -sS "https://api.tonbo.dev/v1/volumes" \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"data","region":"xx-example-1"}'
```

## Read a Volume {#get-volume}

`GET /v1/volumes/{name}` · CLI: `tonbo volume show`

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

A Volume of the account: the live one of the name, or else the latest being deleted. `machine` names the Machine it is bound to, `live_bytes` what the chunk-store meter bills and `last_commit_at` its last committed flush. `writes_held` is non-null while the Machine's writes to it are held until a copy catches up, with since when and why; a held write is never failed. A region this server cannot reach answers 503 `region_unavailable` when the Volume is in no region it read.

### Parameters {#get-volume-parameters}

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | path | string | yes | The Volume's name. 1 to 40 characters. Matches `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`. Never `"self"`. |

### Response {#get-volume-response}

| Status | Answer |
| --- | --- |
| `200` | The Volume |

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

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

**Example 200 body**

```json
{
  "data": {
    "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
    "name": "data",
    "region": "xx-example-1",
    "size_gib": 20,
    "machine": null,
    "state": "available",
    "live_bytes": 0,
    "last_commit_at": null,
    "created_at": "2027-02-15T09:30:00Z",
    "writes_held": null
  }
}
```

### Errors {#get-volume-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)) |
| `404` | [`not_found`](https://tonbo.dev/docs/reference/management.md#not_found) | No live resource of the key’s account has that name or id, or the key is narrowed away from it. | No | Check the name, and that the key belongs to the account that holds it; list the resources to see what exists. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#not_found)) |
| `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)) |
| `503` | [`region_unavailable`](https://tonbo.dev/docs/reference/management.md#region_unavailable) | The region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After. | After Retry-After | Send the request again after Retry-After; if `detail` says the region takes no new resource of this kind, name another region. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#region_unavailable)) |

### Retries {#get-volume-retries}

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

**Request**

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

## Delete a Volume {#delete-volume}

`DELETE /v1/volumes/{name}` · CLI: `tonbo volume delete`

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

A Volume bound to a Machine answers 409 `conflict`: remove it from the Machine first (`volumes: []`). Otherwise the Volume enters `deleting` and is purged: its data key is destroyed first, then its objects and its ledger (contracts/machines/volume-v1.json `deletion`); its name is free at once. The answer is 202 with the Volume being deleted, and again for a Volume already deleting. There are no Volume snapshots or backups, so a deleted Volume cannot be recovered.

### Parameters {#delete-volume-parameters}

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | path | string | yes | The Volume's name. 1 to 40 characters. Matches `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`. Never `"self"`. |

### Response {#delete-volume-response}

| Status | Answer |
| --- | --- |
| `202` | The Volume, being deleted |

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

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

**Example 202 body**

```json
{
  "data": {
    "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
    "name": "data",
    "region": "xx-example-1",
    "size_gib": 20,
    "machine": null,
    "state": "available",
    "live_bytes": 0,
    "last_commit_at": null,
    "created_at": "2027-02-15T09:30:00Z",
    "writes_held": null
  }
}
```

### Errors {#delete-volume-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)) |
| `404` | [`not_found`](https://tonbo.dev/docs/reference/management.md#not_found) | No live resource of the key’s account has that name or id, or the key is narrowed away from it. | No | Check the name, and that the key belongs to the account that holds it; list the resources to see what exists. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#not_found)) |
| `409` | [`conflict`](https://tonbo.dev/docs/reference/management.md#conflict) | The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. `detail` says which, and `errors` names the field. | No | Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#conflict)) |
| `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)) |
| `503` | [`region_unavailable`](https://tonbo.dev/docs/reference/management.md#region_unavailable) | The region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After. | After Retry-After | Send the request again after Retry-After; if `detail` says the region takes no new resource of this kind, name another region. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#region_unavailable)) |

### Retries {#delete-volume-retries}

- It takes no Idempotency-Key; its description above says what sending it again does.
- `429` and `503` carry `Retry-After`: wait that many seconds, then send the same request again.

**Request**

```shell
curl -sS -X DELETE "https://api.tonbo.dev/v1/volumes/<name>" \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

## Read a Volume's metrics over a window {#get-volume-name-metrics}

`GET /v1/volumes/{name}/metrics` · CLI: `tonbo volume metrics`

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

One Volume's metrics over a window ending with the current step, by the UTC hour or day: its guest I/O (`read_bytes`, `write_bytes`, `read_ops`, `write_ops`, `trim_ops`), counted as its daemon served its Machine's requests, 0 in a step with none, and `stored_bytes`, what its files held at the step's last sample (taken every 5 minutes, written when it changed), carried from the step before when the step has none and null before its first. Hours go back 8 days and days 92. The I/O updates about every 30 seconds while the Volume is attached and starts with the hour its recording went live. The Volume is the live one of the name, or else the latest being deleted. The latency series (`read_latency_p50_ms`, `read_latency_p99_ms`, `write_latency_p50_ms`, `write_latency_p99_ms`) are the median and 99th percentile time the Volume's daemon took to answer the guest's successful reads and writes, from a request's arrival to its reply, write holds included; the account's are read from every Volume's merged histograms, never an average of percentiles, and a step with no timed request is null. Display only, never billed: what a Volume is billed for is `/usage`. Takes the parameters of `getVolumeMetrics`; `stored_bytes` here also answers hourly.

### Parameters {#get-volume-name-metrics-parameters}

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | path | string | yes | The Volume's name. 1 to 40 characters. Matches `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`. Never `"self"`. |
| `series` | query | string | no | The series to answer, comma-separated, of `stored_bytes`, `read_bytes`, `write_bytes`, `read_ops`, `write_ops`, `trim_ops`, `read_latency_p50_ms`, `read_latency_p99_ms`, `write_latency_p50_ms` and `write_latency_p99_ms`; every series when omitted. Matches `^(stored_bytes\|read_bytes\|write_bytes\|read_ops\|write_ops\|trim_ops\|read_latency_p50_ms\|read_latency_p99_ms\|write_latency_p50_ms\|write_latency_p99_ms)(,(stored_bytes\|read_bytes\|write_bytes\|read_ops\|write_ops\|trim_ops\|read_latency_p50_ms\|read_latency_p99_ms\|write_latency_p50_ms\|write_latency_p99_ms))*$`. |
| `window` | query | one of `"24h"`, `"7d"`, `"30d"` or `"90d"` | no | `24h`, the last 24 UTC hours, hourly; or the last 7, 30 or 90 UTC days, today included, daily (`7d` also hourly with `granularity=hour`). |
| `granularity` | query | one of `"hour"` or `"day"` | no | `hour` or `day`: the step, with `from` and `to` (`day` when omitted), or with `window=7d`. |
| `from` | query | string | no | With `to`, instead of `window`, the window's first step, a UTC hour for `granularity=hour` or a UTC midnight (or a date) by the day. |
| `to` | query | string | no | With `from`, the step boundary the window ends at, exclusive, at most 8 days after `from` by the hour or 92 by the day, and the end of the current step at the latest. |

### Response {#get-volume-name-metrics-response}

| Status | Answer |
| --- | --- |
| `200` | The Volume's metrics |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [VolumeNameMetrics](https://tonbo.dev/docs/reference/management/volumes.md#schema-volume-name-metrics) | yes |  |

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

**Example 200 body**

```json
{
  "data": {
    "name": "<name>",
    "region": "<region>",
    "granularity": "hour",
    "from": "2026-11-02T09:30:00.000Z",
    "to": "2026-11-02T09:30:00.000Z",
    "as_of": "2026-11-02T09:30:00.000Z",
    "points": [
      {
        "start": "2026-11-02T09:30:00.000Z",
        "stored_bytes": 0,
        "read_bytes": 0,
        "write_bytes": 0,
        "read_ops": 0,
        "write_ops": 0,
        "trim_ops": 0,
        "read_latency_p50_ms": 0,
        "read_latency_p99_ms": 0,
        "write_latency_p50_ms": 0,
        "write_latency_p99_ms": 0,
        "partial": false
      }
    ]
  }
}
```

### Errors {#get-volume-name-metrics-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)) |
| `404` | [`not_found`](https://tonbo.dev/docs/reference/management.md#not_found) | No live resource of the key’s account has that name or id, or the key is narrowed away from it. | No | Check the name, and that the key belongs to the account that holds it; list the resources to see what exists. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#not_found)) |
| `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)) |
| `503` | [`region_unavailable`](https://tonbo.dev/docs/reference/management.md#region_unavailable) | The region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After. | After Retry-After | Send the request again after Retry-After; if `detail` says the region takes no new resource of this kind, name another region. ([more](https://tonbo.dev/docs/databases/troubleshooting/manage.md#region_unavailable)) |

### Retries {#get-volume-name-metrics-retries}

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

**Request**

```shell
curl -sS "https://api.tonbo.dev/v1/volumes/<name>/metrics" \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

## Objects {#objects}

### Volume {#schema-volume}

A Volume as contracts/machines/volume-v1.schema.json `$defs.volume` defines it.

The fields below are the contract’s, with their types and limits; [Things to know](https://tonbo.dev/docs/machines/volumes/things-to-know.md) explains what each one does.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Matches `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`. |
| `name` | string | yes | 1 to 40 characters. Matches `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`. Never `"self"`. |
| `region` | string | yes | Matches `^[a-z]{2}(-gov)?-[a-z]+-[0-9]+$`. |
| `size_gib` | integer | yes | 1 to 100. |
| `machine` | object or null | yes |  |
| `machine.id` | string | yes | Matches `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`. |
| `machine.name` | string | yes | 1 to 40 characters. Matches `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`. Never `"self"`. |
| `state` | one of `"available"`, `"bound"`, `"attached"` or `"deleting"` | yes |  |
| `live_bytes` | integer | yes | 0 to 9007199254740991. |
| `last_commit_at` | string (date-time) or null | yes | Matches `Z$`. |
| `created_at` | string (date-time) | yes | Matches `Z$`. |
| `writes_held` | object or null | yes |  |
| `writes_held.since` | string (date-time) | yes | Matches `Z$`. |
| `writes_held.reason` | one of `"budget"`, `"copy_bound"` or `"upload_budget"` | yes |  |
| `for_machine` | string or null | no | 1 to 40 characters. Matches `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`. Never `"self"`. |

**Example Volume**

```json
{
  "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
  "name": "data",
  "region": "xx-example-1",
  "size_gib": 20,
  "machine": null,
  "state": "available",
  "live_bytes": 0,
  "last_commit_at": null,
  "created_at": "2027-02-15T09:30:00Z",
  "writes_held": null
}
```

### VolumeNameMetrics {#schema-volume-name-metrics}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The Volume's name. |
| `region` | string | yes | The Volume's region. |
| `granularity` | one of `"hour"` or `"day"` | yes | `hour` or `day`: one point per UTC hour or day. |
| `from` | string (date-time) | yes | The window's first instant, a UTC hour or midnight. |
| `to` | string (date-time) | yes | The instant the window ends, exclusive. |
| `as_of` | string (date-time) or null | yes | When the latest step read was last written; null when the window holds none. |
| `points` | array of [VolumeMetricPoint](https://tonbo.dev/docs/reference/management/usage.md#schema-volume-metric-point) | yes | Every step of the window, oldest first. |

**Example VolumeNameMetrics**

```json
{
  "name": "<name>",
  "region": "<region>",
  "granularity": "hour",
  "from": "2026-11-02T09:30:00.000Z",
  "to": "2026-11-02T09:30:00.000Z",
  "as_of": "2026-11-02T09:30:00.000Z",
  "points": [
    {
      "start": "2026-11-02T09:30:00.000Z",
      "stored_bytes": 0,
      "read_bytes": 0,
      "write_bytes": 0,
      "read_ops": 0,
      "write_ops": 0,
      "trim_ops": 0,
      "read_latency_p50_ms": 0,
      "read_latency_p99_ms": 0,
      "write_latency_p50_ms": 0,
      "write_latency_p99_ms": 0,
      "partial": false
    }
  ]
}
```
