# Cache volumes

[Cache volumes](/docs/agent/buildkite-hosted/cache-volumes) are external volumes attached to [Buildkite hosted agent](/docs/agent/buildkite-hosted) instances in a cluster. Use these endpoints to list and delete a cluster's cache volumes.

This API is available to organizations with Buildkite hosted agents enabled. For non-hosted clusters, the list endpoint returns an empty list, and the delete endpoint returns `404 Not Found`.

## Cache volume data model



| `id` | ID of the cache volume |
| --- | --- |
| `tag` | The cache tag identifying this volume (for example, `pipeline-uuid/node-modules`) |
| `cluster_id` | ID of the cluster the cache volume belongs to |
| `size_mb` | Size of the cache volume in megabytes |
| `created_at` | When the cache volume was created |
| `attached_at` | When the cache volume was last attached to an agent |
| `detached_at` | When the cache volume was last detached from an agent |



## List cache volumes

Returns the list of cache volumes for a cluster. Non-hosted clusters and hosted clusters with no cache volumes return an empty list.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/cache_volumes"
```

```json
[
  {
    "id": "vol-01j9z1p0qr3s4t5u6v7w8x9y0z",
    "tag": "pipeline-uuid/node-modules",
    "cluster_id": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "size_mb": 20480,
    "created_at": "2024-10-01T00:00:00.000Z",
    "attached_at": "2024-10-15T08:00:00.000Z",
    "detached_at": "2024-10-15T08:30:00.000Z"
  }
]
```

Required scope: `read_clusters`

Success response: `200 OK`

Error responses:



| `503 Service Unavailable` | `{ "message": "Could not load cache volumes: reason" }` |
| --- | --- |



## Delete a cache volume

Deletes a cache volume by its tag. Cache tags can contain `/` and `;`. The tag is passed in the request body rather than as a URL path segment.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/cache_volumes" \
  -H "Content-Type: application/json" \
  -d '{ "tag": "pipeline-uuid/node-modules" }'
```

Required [request body properties](/docs/api#request-body-properties):



| `tag` | The cache tag identifying the volume to delete. _Example:_ `"pipeline-uuid/node-modules"` |
| --- | --- |



Required scope: `write_clusters`

Success response: `204 No Content`

Error responses:



| `400 Bad Request` | `{ "message": "`tag` must be a non-empty string" }` |
| --- | --- |
| `404 Not Found` | `{ "message": "No cache volume found for tag: tag-value" }` |
| `404 Not Found` | `{ "message": "This cluster has no hosted cache volumes" }` |
| `503 Service Unavailable` | `{ "message": "Could not delete cache volume: reason" }` |