Clusters API

The clusters API endpoint lets you create and manage clusters in your organization, along with the following other aspects associated with clusters:

`id`	ID of the cluster
`graphql_id`	GraphQL ID of the cluster
`default_queue_id`	ID of the cluster's default queue. Agents that connect to the cluster without specifying a queue will accept jobs from this queue.
`agent_tracing_service_uuid`	UUID of the OpenTelemetry notification service used to automatically configure agent tracing, or `null` when none is selected. Only included in responses for callers with manage cluster permission.
`name`	Name of the cluster
`description`	Description of the cluster
`emoji`	Emoji for the cluster using the emoji syntax
`color`	Color hex code for the cluster
`maintainers`	The maintainers of the cluster
`url`	Canonical API URL of the cluster
`web_url`	URL of the cluster on Buildkite
`queues_url`	API URL of the cluster's queues
`default_queue_url`	API URL of the cluster's default queue
`created_at`	When the cluster was created
`created_by`	User who created the cluster
`hosted_git_mirror_enabled`	Whether the hosted-agent git mirror cache is enabled for the cluster. Only included in responses for callers with manage cluster permission. Only applicable to clusters running Buildkite hosted agents.
`hosted_container_cache_enabled`	Whether the hosted-agent container cache is enabled for the cluster. Only included in responses for callers with manage cluster permission. Only applicable to clusters running Buildkite hosted agents.
`default_cache_registry_uuid`	UUID of the cluster's default cache registry. Only included in responses for callers with manage cluster permission.
`default_cache_registry_url`	API URL of the cluster's default cache registry. Only included in responses for callers with manage cluster permission.

`description`	Description for the cluster. Example: `"A place for safely running our open source builds"`
`emoji`	Emoji for the cluster using the emoji syntax Example: `":technologist:"`
`color`	Color hex code for the cluster. Example: `"#FFE0F1"`
`agent_tracing_service_uuid`	UUID of an enabled OpenTelemetry notification service in the same organization, scoped to all pipelines with no branch filter. Use the service's UUID, not its GraphQL ID. Omit this property or set it to `null` to leave automatic agent tracing unconfigured. Agents need version 3.136.1 or later. Example: `"00000000-0000-4000-8000-000000000001"`
`maintainers`	An array of one or more hashes of representing users or teams to grant maintainer permissions to for this cluster. Example: `[{ "user": "282a043f-4d4f-4db5-ac9a-58673ae02caf" }, { "team": "0da645b7-9840-428f-bd80-0b92ee274480" }]`

`422 Unprocessable Entity`	`{ "message": "Validation failed: Reason for failure" }`

The hosted_git_mirror_enabled, hosted_container_cache_enabled, and default_cache_registry_uuid fields can only be set when updating a cluster. Cluster creation requests do not apply these fields.

For example, to change the cluster's default cache registry:

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{id}" \
  -H "Content-Type: application/json" \
  -d '{ "default_cache_registry_uuid": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d" }'

To configure automatic agent tracing, set agent_tracing_service_uuid to an eligible OpenTelemetry notification service UUID:

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{id}" \
  -H "Content-Type: application/json" \
  -d '{ "agent_tracing_service_uuid": "00000000-0000-4000-8000-000000000001" }'

Omit this property to keep the current selection, or set it to null to disable automatic configuration. Only newly registered agents receive changes. Already registered agents keep their configuration until they restart or reconnect, including after automatic configuration is disabled. Local OTLP destination settings take precedence. See Automatically configure agent OpenTelemetry tracing for a cluster for setup and credential security guidance.

`name`	Name for the cluster. Example: `"Open Source"`
`description`	Description for the cluster. Example: `"A place for safely running our open source builds"`
`emoji`	Emoji for the cluster using the emoji syntax. Example: `":technologist:"`
`color`	Color hex code for the cluster. Example: `"#FFE0F1"`
`default_queue_id`	ID of the queue to set as the cluster's default queue. Agents that connect to the cluster without specifying a queue will accept jobs from this queue. Example: `"01885682-55a7-44f5-84f3-0402fb452e66"`
`agent_tracing_service_uuid`	UUID of an enabled OpenTelemetry notification service in the same organization, scoped to all pipelines with no branch filter. Use the service's UUID, not its GraphQL ID. Omit this property to keep the current selection, or set it to `null` to disable automatic agent tracing. Requires permission to manage the cluster. Example: `"00000000-0000-4000-8000-000000000001"`
`default_cache_registry_uuid`	UUID of the cache registry to set as the cluster's default. Must be the UUID of a cache registry in this cluster. A registry slug isn't accepted. The value can't be `null`, because a cluster must always have a default cache registry. Requires permission to manage the cluster. Example: `"b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d"`
`hosted_git_mirror_enabled`	Enable or disable the hosted-agent git mirror cache for the cluster. Must be `true` or `false`. Only applicable to clusters running Buildkite hosted agents. Example: `true`
`hosted_container_cache_enabled`	Enable or disable the hosted-agent container cache for the cluster. Must be `true` or `false`. Only applicable to clusters running Buildkite hosted agents. Example: `true`

Required scope: write_clusters

Success response: 200 OK

Error responses:

`422 Unprocessable Entity`	A hosted-agent cache field is not `true` or `false`, a changed cache field targets a non-hosted cluster, `default_cache_registry_uuid` isn't the UUID of a cache registry in this cluster (for example, it's a slug, `null`, or the UUID of a deleted registry or a registry in another cluster), or another cluster validation fails.
`503 Service Unavailable`	A change to `hosted_git_mirror_enabled` could not be applied by the hosted-agent service. The update is rolled back and is safe to retry.

Delete a cluster

Delete a cluster along with any queues and tokens that belong to it.

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

Required scope: write_clusters

Success response: 204 No Content

Error responses:

`422 Unprocessable Entity`	`{ "message": "Reason the cluster couldn't be deleted" }`

Clusters API

Clusters

Cluster data model

List clusters

Get a cluster

Create a cluster

Update a cluster

Delete a cluster