# Queues [Queues](/docs/agent/queues/managing) define discrete groups of agents within a [Buildkite cluster](/docs/pipelines/security/clusters). 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](/docs/apis/graphql-api#graphql-ids) 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 | | `hosted_agents.agent_image_ref` | The custom image URL configured for the queue's hosted agents. Only present on Buildkite hosted queues. This field is a [private preview](/docs/agent/buildkite-hosted/linux/custom-base-images#use-an-agent-image-specify-a-custom-image-for-a-queue) feature. | | `created_at` | When the queue was created | | `created_by` | User who created the queue | ## List queues Returns a [paginated list](/docs/rest-api#pagination) of a cluster's queues. ```bash curl -H "Authorization: Bearer $TOKEN" \ -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues" ``` ```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/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", "retry_agent_affinity": "prefer-warmest", "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 ```bash curl -H "Authorization: Bearer $TOKEN" \ -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues/{queue.id}" ``` ```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/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", "retry_agent_affinity": "prefer-warmest", "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 ```bash 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" }' ``` ```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/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", "retry_agent_affinity": "prefer-warmest", "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](/docs/api#request-body-properties): | `key` | Key for the queue. _Example:_ `"default"` | | --- | --- | Optional [request body properties](/docs/api#request-body-properties): | `description` | Description for the queue. _Example:_ `"The default queue for this cluster"` `retry_agent_affinity` | When a job is retried, this setting controls how agents are selected for these retries. This value must be either `prefer-warmest` (default), which preferences retries on agents that have recently finished jobs, or `prefer-different`, which preferences retries on different agents, if they're available. If this property is omitted, then the value `prefer-warmest` is used. _Example:_ `"prefer-different"` | | --- | --- | --- | Required scope: `write_clusters` Success response: `201 Created` Error responses: | `422 Unprocessable Entity` | `{ "message": "Validation failed: Reason for failure" }` | | --- | --- | ## Create a Buildkite hosted queue ```bash 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" } }' ``` ```json { "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](/docs/api#request-body-properties): | `key` | Key for the queue. _Example:_ `"default"` | | --- | --- | Optional [request body properties](/docs/api#request-body-properties): | `description` | Description for the queue. _Example:_ `"The default queue for this cluster"` | `hostedAgents` | Configures this queue to use [Buildkite hosted agents](/docs/agent/buildkite-hosted), along with its _instance shape_. This makes the queue a [Buildkite hosted queue](/docs/agent/queues/managing#create-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](#instance-shape-values-for-linux) and [macOS](#instance-shape-values-for-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 ```bash 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" }' ``` ```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/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](/docs/api#request-body-properties): | `description` | Description for the queue. _Example:_ `"The default queue for this cluster"` | `retry_agent_affinity` | Controls how agents are selected for retries. Must be one of `prefer-warmest` or `prefer-different`. _Example:_ `"prefer-warmest"` | | --- | --- | --- | --- | | `hostedAgents` | Updates the _instance shape_ for an existing [Buildkite hosted queue](/docs/agent/queues/managing#create-a-buildkite-hosted-queue), which in turn manages [Buildkite hosted agents](/docs/agent/buildkite-hosted). _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](#instance-shape-values-for-linux) and [macOS](#instance-shape-values-for-macos) Buildkite hosted agents. `agentImageRef` (optional, [private preview](/docs/agent/buildkite-hosted/linux/custom-base-images#use-an-agent-image-specify-a-custom-image-for-a-queue)): A custom image URL to use for agents in this queue. When set, this overrides the [default agent image](/docs/agent/buildkite-hosted/linux/custom-base-images#use-an-agent-image-set-the-default-image-for-a-queue) selected through the Buildkite interface. The image must be publicly available or pushed to the [internal container registry](/docs/pipelines/hosted-agents/internal-container-registry). Contact [support@buildkite.com](mailto:support@buildkite.com) to enable this feature for your organization. Also be aware that this property must be specified with `instanceShape`, even if you are not changing its value. In such circumstances, specify this property's current value. _Example:_ `{ "instanceShape": "LINUX_AMD64_2X4", "agentImageRef": "my-custom-image:latest" }` | Required scope: `write_clusters` Success response: `200 OK` Error responses: | `422 Unprocessable Entity` | `{ "message": "Validation failed: Reason for failure" }` | | --- | --- | ## Delete a queue ```bash 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](/docs/agent/queues/managing#pause-and-resume-a-queue) to prevent jobs from being dispatched to agents associated with the queue. ```bash 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" }' ``` ```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": 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](/docs/api#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 ```bash 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" ``` ```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. | `LINUX_AMD64_2X4` | Small | AMD64 | 2 | 4 GB | 47 GB | | --- | --- | --- | --- | --- | --- | | `LINUX_AMD64_4X16` | Medium | AMD64 | 4 | 16 GB | 95 GB | | `LINUX_AMD64_8X32` | Large | AMD64 | 8 | 32 GB | 158 GB | | `LINUX_AMD64_16X64` | Extra Large | AMD64 | 16 | 64 GB | 284 GB | | `LINUX_ARM64_2X4` | Small | ARM64 2 | 4 GB | 47 GB | | `LINUX_ARM64_4X16` | Medium | ARM64 | 4 | 16 GB | 95 GB | | `LINUX_ARM64_8X32` | Large | ARM64 | 8 | 32 GB | 158 GB | | `LINUX_ARM64_16X64` | Extra Large | ARM64 | 16 | 64 GB | 284 GB | ## Instance shape values for macOS Specify the appropriate **Instance shape** for the `instanceShape` value in your REST API call. | `MACOS_ARM64_M4_6X28` | Medium | 6 | 28 GB | 182 GB | | --- | --- | --- | --- | --- | | `MACOS_ARM64_M4_12X56` | Large | 12 | 56 GB | 294 GB | **Note:** Shapes `MACOS_M2_4X7`, `MACOS_M2_6X14`, `MACOS_M2_12X28`, `MACOS_M4_12X56` were deprecated and removed on July 1, 2025.