Test Scheduler pools API

The Test Scheduler pools API lets you manage test pools. Each pool belongs to an organization, test suite, pipeline, and build. Authenticate requests using a suite-scoped OIDC token.

List pools

Returns a cursor-paginated list of test pools for the build identified by the OIDC token. Results are limited to the organization, test suite, pipeline, and build associated with the token.

curl --get "https://api.buildkite.com/v2/organizations/{org.slug}/test-scheduler/pools" \
  --header "Authorization: Bearer $OIDC_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode "pipeline_id={pipeline.uuid}" \
  --data-urlencode "build_id={build.uuid}"

{
  "items": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "organization_id": "01234567-89ab-cdef-0123-456789abcdef",
      "suite_id": "01234567-89ab-cdef-0123-456789abcdef",
      "pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
      "build_id": "01234567-89ab-cdef-0123-456789abcdef",
      "key": "my-pool",
      "state": "populating",
      "expires_at": "2025-01-01T00:00:00.000Z",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  ],
  "links": {
    "next": "https://api.buildkite.com/v2/organizations/my-org/test-scheduler/pools?pipeline_id=01234567-89ab-cdef-0123-456789abcdef&build_id=01234567-89ab-cdef-0123-456789abcdef&after=..."
  }
}

Required query string parameters:

`pipeline_id`	The UUID of the pipeline. Must match the `pipeline_id` claim in the OIDC token. Example: `01234567-89ab-cdef-0123-456789abcdef`
`build_id`	The UUID of the build. Must match the `build_id` claim in the OIDC token. Example: `01234567-89ab-cdef-0123-456789abcdef`

Optional query string parameters:

`key`	Filters results to pools whose key matches this value (case-insensitive). Omitting this parameter returns all pools for the build. A non-blank string value is required if provided. Example: `my-pool`
`per_page`	The number of results per page. Must be between 1 and 100. Defaults to 30. Example: `10`
`after`	Returns results after this cursor. Use the `links.next` URL from the previous response to paginate forward.
`before`	Returns results before this cursor. Use the `links.prev` URL from the previous response to paginate backward. Cannot be used together with `after`.

Results are ordered from newest to oldest. The API returns an empty items array when no pools match the request.

Required scope: read_test_pool

Success response: 200 OK

Error responses:

400 Bad Request: Missing or malformed pipeline_id, build_id, key, or pagination parameters.
403 Forbidden: The pipeline_id or build_id does not match the OIDC token claims, or the token lacks the read_test_pool scope.

Get a pool

Returns the details of a test pool.

curl "https://api.buildkite.com/v2/organizations/{org.slug}/test-scheduler/pools/{pool.id}" \
  --header "Authorization: Bearer $OIDC_TOKEN" \
  --header "Accept: application/json"

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "organization_id": "01234567-89ab-cdef-0123-456789abcdef",
  "suite_id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
  "build_id": "01234567-89ab-cdef-0123-456789abcdef",
  "key": "my-pool",
  "state": "populating",
  "expires_at": "2025-01-01T00:00:00.000Z",
  "created_at": "2025-01-01T00:00:00.000Z"
}

Required scope: read_test_pool

Success response: 200 OK

Create a pool

Creates a test pool for a build.

curl "https://api.buildkite.com/v2/organizations/{org.slug}/test-scheduler/pools" \
  --request POST \
  --header "Authorization: Bearer $OIDC_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "suite": "my-suite",
    "pipeline": "my-pipeline",
    "build_id": "01234567-89ab-cdef-0123-456789abcdef",
    "key": "my-pool",
    "ttl_seconds": 3600
  }'

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "organization_id": "01234567-89ab-cdef-0123-456789abcdef",
  "suite_id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
  "build_id": "01234567-89ab-cdef-0123-456789abcdef",
  "key": "my-pool",
  "state": "populating",
  "expires_at": "2025-01-01T01:00:00.000Z",
  "created_at": "2025-01-01T00:00:00.000Z"
}

Required request body properties:

`suite`	The slug of the test suite. Example: `my-suite`
`pipeline`	The slug of the pipeline. Example: `my-pipeline`
`build_id`	The UUID of the build. Example: `01234567-89ab-cdef-0123-456789abcdef`
`key`	The key used to identify the pool. Example: `my-pool`

Optional request body properties:

`ttl_seconds`	The time-to-live for the pool in seconds. The pool expires and is no longer available after this duration. If omitted, the API uses the default time-to-live. Example: `3600`

Required scope: write_test_pool

Success response: 201 Created