Cache volumes

Cache volumes are external volumes attached to Buildkite hosted agent 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.

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

[
  {
    "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.

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:

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