Clusters API

The clusters API endpoint lets you create and manage clusters in your organization.

Clusters

A 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
`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

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

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

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

Request body properties:

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

Required scope: write_clusters

Success response: 200 OK

Error responses:

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

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

Queues

Queues are discrete groups of agents within a cluster. Pipelines in that cluster can target queues to run jobs on agents assigned to those queues.

Queue data model

`id`	ID of the queue
`graphql_id`	GraphQL ID of the queue
`key`	The queue key
`description`	Description of the queue
`url`	Canonical API URL of the queue
`web_url`	URL of the queue on Buildkite
`cluster_url`	API URL of the cluster the queue belongs to
`dispatch_paused`	Indicates whether the queue has paused dispatching jobs to associated agents
`dispatch_paused_by`	User who paused the queue
`dispatch_paused_at`	When the queue was paused
`dispatch_paused_note`	The note left when the queue was paused
`created_at`	When the queue was created
`created_by`	User who created the queue

List queues

Returns a paginated list of a cluster's queues.

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

[
  {
    "id": "01885682-55a7-44f5-84f3-0402fb452e66",
    "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
    "key": "default",
    "description": "The default queue for this cluster",
    "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
    "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
    "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "dispatch_paused": false,
    "dispatch_paused_by": null,
    "dispatch_paused_at": null,
    "dispatch_paused_note": null,
    "created_at": "2023-05-03T04:17:55.867Z",
    "created_by": {
      "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
      "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
      "name": "Sam Kim",
      "email": "sam@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/example",
      "created_at": "2023-05-03T04:17:43.118Z"
    }
  }
]

Required scope: read_clusters

Success response: 200 OK

Get a queue

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

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "dispatch_paused": false,
  "dispatch_paused_by": null,
  "dispatch_paused_at": null,
  "dispatch_paused_note": null,
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Required scope: read_clusters

Success response: 200 OK

Create a self-hosted queue

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues" \
  -H "Content-Type: application/json" \
  -d '{ "key": "default", "description": "The default queue for this cluster" }'

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "dispatch_paused": false,
  "dispatch_paused_by": null,
  "dispatch_paused_at": null,
  "dispatch_paused_note": null,
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Required request body properties:

`key`	Key for the queue. Example: `"default"`

Required scope: write_clusters

Success response: 201 Created

Error responses:

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

Create a Buildkite hosted queue

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues" \
  -H "Content-Type: application/json" \
  -d '{ "key": "default", "description": "Queue of hosted Buildkite agents", "hostedAgents": { "instanceShape": "LINUX_AMD64_2X4" } }'

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "Queue of hosted Buildkite agents",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "dispatch_paused": false,
  "dispatch_paused_by": null,
  "dispatch_paused_at": null,
  "dispatch_paused_note": null,
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  },
  "hosted": true,
  "hosted_agents": {
    "instance_shape": {
      "machine_type": "linux",
      "architecture": "amd64",
      "cpu": 2,
      "memory": 4,
      "name": "LINUX_AMD64_2X4"
    }
  }
}

Required request body properties:

`key`	Key for the queue. Example: `"default"`

Optional request body properties:

description Description for the queue.
Example: "The default queue for this cluster"

`description`	Description for the queue. Example: `"The default queue for this cluster"`
`hostedAgents`	Configures this queue to use Buildkite hosted agents, along with its instance shape. This makes the queue a Buildkite hosted queue. Example: `{ "instanceShape": "LINUX_AMD64_2X4" }` `instanceShape` (required when `hostedAgents` is specified): Describes the machine type, architecture, CPU, and RAM to provision for Buildkite hosted agent instances running jobs in this queue. Learn more about the instance shapes available for Linux and macOS hosted agents.

Required scope: write_clusters

Success response: 201 Created

Error responses:

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

Update a queue

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues/{id}" \
  -H "Content-Type: application/json" \
  -d '{ "description": "The default queue for this cluster" }'

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "dispatch_paused": false,
  "dispatch_paused_by": null,
  "dispatch_paused_at": null,
  "dispatch_paused_note": null,
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Request body properties:

description Description for the queue.
Example: "The default queue for this cluster"

hostedAgents Configures this queue to use Buildkite hosted agents, along with its instance shape. This makes the queue a Buildkite hosted queue.
Example:
{ "instanceShape": "LINUX_AMD64_2X4" }
instanceShape (required when hostedAgents is specified): Describes the machine type, architecture, CPU, and RAM to provision for Buildkite hosted agent instances running jobs in this queue.
It is only possible to change the size of the current instance shape assigned to this queue. It is not possible to change the current instance shape's machine type (from macOS to Linux, or vice versa), or for a Linux machine, its architecture (from AMD64 to ARM64, or vice versa).
Learn more about the instance shapes available for Linux and macOS Buildkite hosted agents.

`description`	Description for the queue. Example: `"The default queue for this cluster"`
`hostedAgents`	Configures this queue to use Buildkite hosted agents, along with its instance shape. This makes the queue a Buildkite hosted queue. Example: `{ "instanceShape": "LINUX_AMD64_2X4" }` `instanceShape` (required when `hostedAgents` is specified): Describes the machine type, architecture, CPU, and RAM to provision for Buildkite hosted agent instances running jobs in this queue. It is only possible to change the size of the current instance shape assigned to this queue. It is not possible to change the current instance shape's machine type (from macOS to Linux, or vice versa), or for a Linux machine, its architecture (from AMD64 to ARM64, or vice versa). Learn more about the instance shapes available for Linux and macOS Buildkite hosted agents.

Required scope: write_clusters

Success response: 200 OK

Error responses:

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

Delete a queue

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

Required scope: write_clusters

Success response: 204 No Content

Error responses:

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

Pause a queue

Pause a queue to prevent jobs from being dispatched to agents associated with the queue.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues/{id}/pause_dispatch" \
  -H "Content-Type: application/json" \
  -d '{ "dispatch_paused_note": "Paused while we investigate a security issue" }'

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/01885682-55a7-44f5-84f3-0402fb452e66",
  "dispatch_paused": true,
  "dispatch_paused_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  },
  "dispatch_paused_at": "2023-05-03T04:19:43.118Z",
  "dispatch_paused_note": "Paused while we investigate a security issue",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Optional request body properties:

`note`	Note explaining why the queue is paused. The note will display on the queue page and any affected builds. Example: `"Paused while we investigate a security issue"`

Required scope: write_clusters

Success response: 200 OK

Error responses:

`422 Unprocessable Entity`	`{ "message": "Cluster queue is already paused" }`

Resume a paused queue

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues/{id}/resume_dispatch" \
  -H "Content-Type: application/json"

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/01885682-55a7-44f5-84f3-0402fb452e66",
  "dispatch_paused": false,
  "dispatch_paused_by": null,
  "dispatch_paused_at": null,
  "dispatch_paused_note": null,
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Required scope: write_clusters

Success response: 200 OK

Error responses:

`422 Unprocessable Entity`	`{ "message": "Cluster queue is not paused" }`

Instance shape values for Linux

Specify the appropriate Instance shape for the instanceShape value in your REST API call.

Instance shape	Size	Architecture	vCPU	Memory
Instance shape	Instance shape	`LINUX_AMD64_2X4`	Size	Size	Small	Architecture	Architecture	AMD64	vCPU	vCPU	2	Memory	Memory	4 GB
Instance shape	Instance shape	`LINUX_AMD64_4X16`	Size	Size	Medium	Architecture	Architecture	AMD64	vCPU	vCPU	4	Memory	Memory	16 GB
Instance shape	Instance shape	`LINUX_AMD64_8X32`	Size	Size	Large	Architecture	Architecture	AMD64	vCPU	vCPU	8	Memory	Memory	32 GB
Instance shape	Instance shape	`LINUX_AMD64_16X64`	Size	Size	Extra Large	Architecture	Architecture	AMD64	vCPU	vCPU	16	Memory	Memory	64 GB
Instance shape	Instance shape	`LINUX_ARM64_2X4`	Size	Size	Small	Architecture	Architecture	ARM64	vCPU	vCPU	2	Memory	Memory	4 GB
Instance shape	Instance shape	`LINUX_ARM64_4X16`	Size	Size	Medium	Architecture	Architecture	ARM64	vCPU	vCPU	4	Memory	Memory	16 GB
Instance shape	Instance shape	`LINUX_ARM64_8X32`	Size	Size	Large	Architecture	Architecture	ARM64	vCPU	vCPU	8	Memory	Memory	32 GB
Instance shape	Instance shape	`LINUX_ARM64_16X64`	Size	Size	Extra Large	Architecture	Architecture	ARM64	vCPU	vCPU	16	Memory	Memory	64 GB

Instance shape values for macOS

Specify the appropriate Instance shape for the instanceShape value in your REST API call.

Instance shape	Size	vCPU	Memory
Instance shape	Instance shape	`MACOS_ARM64_M4_6X28`	Size	Size	Medium	vCPU	vCPU	6	Memory	Memory	28 GB
Instance shape	Instance shape	`MACOS_ARM64_M4_12X56`	Size	Size	Large	vCPU	vCPU	12	Memory	Memory	56 GB

Note: Shapes MACOS_M2_4X7, MACOS_M2_6X14, MACOS_M2_12X28, MACOS_M4_12X56 have been deprecated and will be removed on the 1st of July, 2025.

Agent tokens

An agent token is used to connect agents to a cluster.

Token data model

`id`	The ID of the agent token.
`graphql_id`	The GraphQL ID of the token.
`description`	The description of the token.
`allowed_ip_addresses`	A list of permitted CIDR-notation IPv4 addresses that agents must be accessible through, to access this token and connect to your Buildkite cluster.
`url`	The canonical API URL of the token.
`cluster_url`	The API URL of the Buildkite cluster that the token belongs to.
`created_at`	The date and time when the token was created.
`created_by`	The user who created the token.
`expires_at`	The ISO8601 timestamp at which point the token expires and prevents agents configured with this token from re-connecting to their Buildkite cluster.

List tokens

Returns a paginated list of a cluster's agent tokens.

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

[
  {
    "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
    "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
    "description": "Windows agents",
    "allowed_ip_addresses": "202.144.0.0/24",
    "expires_at" : "2026-01-01T00:00:00Z",
    "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
    "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
    "created_at": "2023-05-26T04:21:41.350Z",
    "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 token

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

{
  "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
  "description": "Windows agents",
  "allowed_ip_addresses": "202.144.0.0/24",
  "expires_at" : "2026-01-01T00:00:00Z",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
  "created_at": "2023-05-26T04:21:41.350Z",
  "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

Create a token

Token visibility

To ensure the security of tokens, the value is only included in the response for the request to create the token. Subsequent responses do not contain the token value.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Windows agents", "expires_at": "2025-01-01T00:00:00Z", "allowed_ip_addresses": "202.144.0.0/24" }'

{
  "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
  "description": "Windows agents",
  "expires_at": "2025-01-01T00:00:00Z",
  "allowed_ip_addresses": "202.144.0.0/24",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
  "created_at": "2023-05-26T04:21:41.350Z",
  "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"
  },
  "token": "igo6HEj5fxQbgBTDoDzNaZzT"
}

Required request body properties:

`description`	Description for the token. Example: `"Windows agents"`

Optional request body properties:

`expires_at`	The ISO8601 timestamp at which point the token expires and prevents agents configured with this token from re-connecting to their Buildkite cluster. Example: `2025-01-01T00:00:00Z`

Required scope: write_clusters

Success response: 201 Created

Error responses:

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

Update a token

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens/{id}" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Windows agents", "expires_at": "2025-01-01T00:00:00Z", "allowed_ip_addresses": "202.144.0.0/24" }'

{
  "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
  "description": "Windows agents",
  "allowed_ip_addresses": "202.144.0.0/24",
  "expires_at" : "2026-01-01T00:00:00Z",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
  "created_at": "2023-05-26T04:21:41.350Z",
  "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"
  }
}

Request body properties:

`description`	Description for the token. Example: `"Windows agents"`

Required scope: write_clusters

Success response: 200 OK

Error responses:

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

Revoke a token

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

Required scope: write_clusters

Success response: 204 No Content

Error responses:

`422 Unprocessable Entity`	`{ "message": "Reason the token couldn't be revoked" }`