Clusters API

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

Clusters

A Buildkite cluster is an isolated set of agents and pipelines within an organization.

Cluster data model

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.
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.

List clusters

Returns a paginated list of an organization's clusters.

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

[
  {
    "id": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
    "default_queue_id": "01885682-55a7-44f5-84f3-0402fb452e66",
    "name": "Open Source",
    "description": "A place for safely running our open source builds",
    "emoji": ":technologist:",
    "color": "#FFE0F1",
    "maintainers": {
      "users": [],
      "teams": []
    },
    "url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "web_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "default_queue_url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "queues_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues",
    "created_at": "2023-05-03T04:17:55.867Z",
    "created_by": {
      "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
      "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
      "name": "Sam Kim",
      "email": "sam@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/example",
      "created_at": "2013-08-29T10:10:03.000Z"
    }
  }
]

Required scope: read_clusters

Success response: 200 OK

Get a cluster

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

{
  "id": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "default_queue_id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "name": "Open Source",
  "description": "A place for safely running our open source builds",
  "emoji": ":technologist:",
  "color": "#FFE0F1",
  "maintainers": {
    "users": [
      {
        "id": "56c210cb-474c-47a7-b4ef-5761a1cb91c1",
        "actor": {
          "id": "da206b36-e5ae-4f4a-aca6-07dd478f3a48",
          "graphql_id": "VXNlci0tLWU1N2ZiYTBmLWFiMTQtNGNjMC1iYjViLTY5NTc3NGZmYmZiZQ==",
          "name": "John Smith",
          "email": "john.smith@example.com",
          "type": "user"
        }
      }
    ],
    "teams": [
      {
        "id": "77ec8d4c-edb3-430e-baba-488757a418e2",
        "actor": {
          "id": "c5e09619-8648-4896-a936-9d0b8b7b3fe9",
          "graphql_id": "VGVhbS0tLWM1ZTA5NjE5LTg2NDgtNDg5Ni1hOTM2LTlkMGI4YjdiM2ZlOQ==",
          "name": "Fearless Frontenders",
          "slug": "fearless-frontenders",
        }
      }
    ]
  },
  "url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "web_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "default_queue_url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "queues_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  },
  "hosted_git_mirror_enabled": false,
  "hosted_container_cache_enabled": false
}

Required scope: read_clusters

Success response: 200 OK

Create a cluster

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Open Source",
    "description": "A place for safely running our open source builds",
    "emoji": ":technologist:",
    "color": "#FFE0F1",
  }'

{
  "id": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "default_queue_id": null,
  "name": "Open Source",
  "description": "A place for safely running our open source builds",
  "emoji": ":technologist:",
  "color": "#FFE0F1",
  "maintainers": {
    "users": [],
    "teams": []
  },
  "url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "web_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "default_queue_url": null,
  "queues_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  }
}

Required request body properties:

name Name for the cluster.
Example: "Open Source"

Optional request body properties:

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

Required scope: write_clusters

Success response: 201 Created

Error responses:

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

Update a cluster

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{id}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Open Source" }'

{
  "id": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "default_queue_id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "name": "Open Source",
  "description": "A place for safely running our open source builds",
  "emoji": ":technologist:",
  "color": "#FFE0F1",
  "maintainers": {
    "users": [],
    "teams": []
  },
  "url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "web_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "default_queue_url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "queues_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  },
  "hosted_git_mirror_enabled": false,
  "hosted_container_cache_enabled": false
}

Request body properties:

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

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