# 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](/docs/pipelines/security/oidc).

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

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

```json
{
  "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.

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

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

```bash
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
  }'
```

```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-01T01:00:00.000Z",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

Required [request body properties](/docs/api#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](/docs/api#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`