Queues
Queues define discrete groups of agents within a Buildkite 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"
|
---|---|
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"
}
}
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.