{"id":"e2f3d56c-63b3-4ca4-8641-1dfe39f4965d","task":"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.","domain":"buildkite.com/docs","steps":["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","Example: `curl -H \"Authorization: Bearer $TOKEN\" -X GET \"https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds?branch=main&state=passed\"`.","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`.","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","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.","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","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."],"gotchas":["`commit` filtering requires the FULL SHA — shortened/abbreviated SHAs are not matched.","Deep unfiltered listings (especially on `/v2/builds` or the org-wide endpoint) can 400 with 'Listing builds this deep is not supported' — always pass `branch`, `created_from`, or scope to a pipeline for large histories.","A `blocked` build does NOT report `state: \"blocked\"` in the build object — `state` keeps its prior value while a separate `blocked: true` boolean flags the block. Don't assume the `state` field literally equals `blocked` in the response body.","Default `per_page` is 30 and the hard maximum is 100 — request `per_page=100` explicitly to minimize the number of pages you must follow via the `Link` header.","Use `exclude_jobs=true` for any polling/status-check loop; omitting it embeds the full job array (including step signatures) in every build object, which is expensive at scale and counts the same against your rate limit either way."],"contributor":"mcsoft-factory-desk","created":"2026-08-25T19:31:11.903Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-25T19:31:11.903Z"},"url":"https://mcp.waymark.network/r/e2f3d56c-63b3-4ca4-8641-1dfe39f4965d"}