List and filter Buildkite builds via the REST API, either across all accessible builds, org-wide, or scoped to a single pipeline, and correctly page through paginated results.

Documented steps

1. Three list endpoints exist: `GET /v2/builds` (all builds across all the token's accessible orgs/pipelines), `GET /v2/organizations/{org.slug}/builds` (all builds in one org), and `GET /v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds` (builds in one pipeline). All require scope `read_builds` and return builds newest-first. See https://buildkite.com/docs/apis/rest-api/builds#list-all-builds
2. Example: `curl -H "Authorization: Bearer $TOKEN" -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds?branch=main&state=passed"`.
3. Filter query params (all optional, usable on all three endpoints): `branch` (exact or glob, e.g. `?branch=*dev*`, repeatable via `branch[]=a&branch[]=b`), `commit` (full SHA only, repeatable via `commit[]=`), `state` (one of `creating, scheduled, running, passed, failing, failed, blocked, canceling, canceled, skipped, not_run, finished`; `finished` is shorthand for `passed`+`failed`+`blocked`+`canceled`; repeatable via `state[]=`), `creator` (user UUID), `meta_data[key]=value`, `include_paused`, `include_retried_jobs`.
4. Time filters use ISO 8601: `created_from` / `created_to` (build creation time) and `finished_from` (build finish time). Example: `?created_from=2025-01-08T23:22:05Z&created_to=2025-02-13T23:22:05Z`. See https://buildkite.com/docs/apis/rest-api/builds#list-all-builds
5. Use `exclude_jobs=true` when you only need build metadata (branch/commit/creator/timestamps/state) — it skips embedding each build's job array, which is the bulk of the payload. Add `exclude_pipeline=true` too if you don't need expanded pipeline info.
6. Pagination is page-based via the `Link` response header (rel=`next`,`prev`,`first`,`last`), controlled by query params `page` (default 1) and `per_page` (default 30, max 100). Fetch with `curl -i ...` to see the `Link` header, then follow the `next` URL until it's absent. See https://buildkite.com/docs/apis/rest-api#pagination
7. If a query returns too large/deep a result set without narrowing filters, the API returns `400 Bad Request` with `{"message": "Listing builds this deep is not supported. Please narrow your query using filters such as branch or created_from."}` — add `branch`, `created_from`/`created_to`, or a pipeline scope to fix this.