> ## Documentation Index > Fetch the complete documentation index at: https://docs.trunk.io/llms.txt > Use this file to discover all available pages before exploring further. # List a pull request's queue-entry state history > Returns the state transitions of this pull request's queue entry. Defaults to **oldest first** — the one list in this API that does, because it is an append-only log a reader replays forward — so finding the CURRENT transition means paging to the end, and `hasMore: false` is how you know you are there. Send `direction=newest` for v1's `includeTimeline` order, where the current transition is the first row of the first page. A pull request that was never enqueued is a 200 with an empty page, not a 404. ## OpenAPI ````yaml /openapi-v2.json get /v2/pull-requests/{id}/queue-entry-history openapi: 3.1.0 info: title: Trunk API version: 2.0.0 description: >- The Trunk public API. Every endpoint is scoped to a single organization and requires a credential. ## Authentication For automation, send an API key as `Authorization: Bearer `. An organization admin creates one in the Trunk app under **Settings → Developer → API Keys**, and chooses the merge-queue permissions it holds. A key with no permissions can read merge queues but change nothing. Those permissions scope merge queue only: every key can use the Flaky Tests and Dynamic CI endpoints, including their writes, whatever permissions it holds. A short-lived first-party token in the `x-trunk-token` header is what the `trunk` CLI sends after `trunk auth login`. A GitHub Actions job can upload impacted targets with no Trunk secret: the `trunk-io/login` action exchanges the run's own GitHub credential (its OIDC token, or on a pull request from a fork its `GITHUB_TOKEN`) for a short-lived first-party token. That token is accepted only by `PUT /v2/impacted-targets`, for the run's own repository — and on a fork pull request, only for that pull request and its head sha. ## Errors Every 4xx and 5xx response is a `ErrorResponse`: `{ "error": { "code", "message" } }`. Switch on `code`, which is stable; `message` is prose and may change at any time. **An authorization denial on a read is reported as `404`, not `403`** — whether a resource exists must not leak across organizations, so a resource in another organization is indistinguishable from one that does not exist. `403 INSUFFICIENT_PERMISSIONS` means the credential is valid but is not permitted the action (or carries no organization). Every response carries an `X-Request-Id` header. Quote it in support requests. ## Rate limiting Requests are limited per organization (currently 100 requests/second). Exceeding it returns `429` with `RATE_LIMIT_EXCEEDED`; retry with backoff. Note that the limit is enforced at the edge, which does not yet wrap its `429` in the `ErrorResponse` envelope described above — treat any `429` as rate limiting regardless of body. ## Compatibility Within v2, Trunk may add: new endpoints, new **optional** response fields, new members to any enum (including new `code` values, new queue-entry states, and new providers), and new optional request parameters. **Clients must tolerate values and fields they do not recognize** rather than failing closed — a client that switches exhaustively over an enum will break when a member is added. Removals and semantic changes require a new major version. ## Provider support Merge queues, verification runs and checks are **GitHub-only** today; `Check.provider` has a single member for that reason. Impacted-target uploads additionally require a `github.com` repository named `owner/repo`. The `Provider` enum lists values the repository index can store, not surfaces that are fully supported. ## Not yet available A pull request's numeric **position** in its queue is not exposed, and list responses are not ordered by queue position. `GET /v2/merge-queues/{id}/order` returns the order the engine will consider pull requests in, but an array index there is not a wait: use a pending entry's `directlyAhead` rather than counting, and `GET /v2/pull-requests/{id}/queue-entry-estimate` for when it is expected to merge (on queues that serve estimates). This API delivers no events of its own — poll it, or subscribe to [Merge Queue's webhooks](https://docs.trunk.io/merge-queue/webhooks). `Idempotency-Key` is not yet honored, so a mutation that times out must be reconciled by reading the resource back rather than blindly retried. contact: name: Trunk Support url: https://docs.trunk.io servers: - url: https://api.trunk.io description: Production security: - apiKey: [] - trunkToken: [] tags: - name: mergeQueues x-group: Merge Queues - name: pullRequests x-group: Pull Requests - name: mergeQueueVerificationRuns x-group: Verification Runs - name: impactedTargets x-group: Impacted Targets - name: repositories x-group: Repositories - name: dynamicCi x-group: Dynamic CI - name: ciJobs x-group: CI Jobs - name: ciWorkflowRuns x-group: CI Workflow Runs - name: ciFailureClusters x-group: CI Failure Clusters - name: testCollections x-group: Test Collections - name: tests x-group: Tests - name: testUploads x-group: Test Uploads paths: /v2/pull-requests/{id}/queue-entry-history: get: tags: - pullRequests summary: List a pull request's queue-entry state history description: >- Returns the state transitions of this pull request's queue entry. Defaults to **oldest first** — the one list in this API that does, because it is an append-only log a reader replays forward — so finding the CURRENT transition means paging to the end, and `hasMore: false` is how you know you are there. Send `direction=newest` for v1's `includeTimeline` order, where the current transition is the first row of the first page. A pull request that was never enqueued is a 200 with an empty page, not a 404. operationId: pullRequests.queueEntryHistory parameters: - schema: type: string format: uuid description: The pull request's id. example: 0f8fad5b-d9cb-469f-a165-70867728950e required: true description: The pull request's id. name: id in: path - schema: type: integer minimum: 1 maximum: 100 default: 25 description: Page size, between 1 and 100. example: 25 required: false description: Page size, between 1 and 100. name: limit in: query - schema: type: string description: >- Opaque cursor from a previous response's `nextCursor`. A cursor is bound to the operation and filter it was minted for. example: AQEKZm9vYmFy required: false description: >- Opaque cursor from a previous response's `nextCursor`. A cursor is bound to the operation and filter it was minted for. name: cursor in: query - schema: type: boolean default: false description: >- Set true to include `total` in the response. Costs an extra COUNT query, so it is off by default. example: false required: false description: >- Set true to include `total` in the response. Costs an extra COUNT query, so it is off by default. name: includeTotal in: query - schema: type: string enum: - oldest - newest default: oldest description: >- Order of the transitions within a timeline. `oldest` (the default) reads the log forward; `newest` matches v1's `includeTimeline` order, so the current transition is the first row rather than the last. example: oldest required: false description: >- Order of the transitions within a timeline. `oldest` (the default) reads the log forward; `newest` matches v1's `includeTimeline` order, so the current transition is the first row rather than the last. name: direction in: query responses: '200': description: A page of state transitions content: application/json: schema: $ref: '#/components/schemas/QueueEntryHistoryList' '400': description: '`VALIDATION_FAILED` | `INVALID_CURSOR`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: VALIDATION_FAILED: summary: VALIDATION_FAILED value: error: code: VALIDATION_FAILED message: 'Invalid input: expected string, received undefined' INVALID_CURSOR: summary: INVALID_CURSOR value: error: code: INVALID_CURSOR message: Invalid or expired cursor. '401': description: '`AUTHENTICATION_REQUIRED` | `INVALID_TOKEN`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: AUTHENTICATION_REQUIRED: summary: AUTHENTICATION_REQUIRED value: error: code: AUTHENTICATION_REQUIRED message: No credential was supplied INVALID_TOKEN: summary: INVALID_TOKEN value: error: code: INVALID_TOKEN message: The supplied token failed verification '404': description: '`PR_NOT_FOUND`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: PR_NOT_FOUND: summary: PR_NOT_FOUND value: error: code: PR_NOT_FOUND message: Pull request not found '429': description: '`RATE_LIMIT_EXCEEDED`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: RATE_LIMIT_EXCEEDED: summary: RATE_LIMIT_EXCEEDED value: error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded; retry after the Retry-After delay '500': description: '`INTERNAL_ERROR`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: INTERNAL_ERROR: summary: INTERNAL_ERROR value: error: code: INTERNAL_ERROR message: An unexpected error occurred components: schemas: QueueEntryHistoryList: type: object properties: data: type: array items: $ref: '#/components/schemas/QueueEntryStateTransition' maxItems: 100 nextCursor: type: - string - 'null' description: >- Opaque cursor for the next page, or null on the last page. Pass it back verbatim as `cursor`; do not construct or inspect one. example: AQEKZm9vYmFy hasMore: type: boolean description: True when another page is available. example: true total: type: integer description: >- Total rows matching the filter. Present only when the request set `includeTotal=true`. example: 1247 required: - data - nextCursor - hasMore ErrorResponse: type: object properties: error: type: object properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable description of what went wrong. Not stable — do not parse. example: An unexpected error occurred required: - code - message required: - error description: >- The uniform error envelope. Every 4xx and 5xx response in this API has this shape. QueueEntryStateTransition: type: object properties: pullRequestId: type: string description: >- Whose queue entry this transition belongs to. Constant on a single pull request's history; on the batch read (`GET /v2/queue-entry-history`) one page spans several, and this is what you group by. example: 6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b state: $ref: '#/components/schemas/QueueEntryState' changedAt: type: string format: date-time description: When the entry entered this state. example: '2026-07-28T11:10:00.000Z' reason: type: - string - 'null' description: >- Why the entry entered this state. `null` for `testing` and `pendingFailure`, which carry no reason. The values below are the vocabulary in use today, grouped by the state they accompany. **This is an open set** — it is the engine's own vocabulary and new values may appear within v2, so match on the values you care about and treat anything else as unclassified rather than failing closed. **Why an entry is waiting (`notReady`)** — `USER_REQUESTED`, `TRUNK_ADMIN_REQUESTED`, `API_REQUESTED`. **Why an entry (re)entered the line (`pending`)** — these are what distinguish a restart's cause: | Value | Meaning | | --- | --- | | `TESTS_RESTARTED_BY_USER` | A person restarted the tests. | | `TESTS_RESTARTED_BY_API_REQUEST` | Restarted through the API — e.g. `pullRequests.restartTests`. | | `MERGE_ITEM_NOW_READY` | A readiness condition became satisfied. | | `MANUAL_PUSH_TO_TARGET_BRANCH` | Someone pushed to the target branch, invalidating the tested state. | | `PREREQUISITE_MERGE_ITEM_FAILED` | An entry ahead of this one failed, so this one must re-test. | | `PREREQUISITE_MERGE_ITEM_CANCELLED` | An entry ahead was removed. | | `PREREQUISITE_MERGE_ITEM_MANUALLY_MERGED` | An entry ahead was merged outside the queue. | | `SKIP_THE_LINE_INTERRUPTED` | A higher-priority entry preempted this one. | | `BISECTION_REQUIRED` | A batch failed and the engine is bisecting to find the culprit. | | `BISECTION_TEST_RUN_PASSED` | A bisection run cleared this entry. | **Why verification passed (`testsPassed`)** — `TEST_RUN_PASSED`, `SUCCESSOR_TEST_RUN_PASSED`, `PASSED_BY_OPTIMIZATION`. **Why an entry failed (`failed`)** — `TEST_RUN_REQUIRED_STATUS_FAILED`, `TEST_RUN_TIMEOUT`, `TEST_RUN_FAILED_BY_OPTIMIZATION`, `START_TEST_RUN_MERGE_CONFLICT`, `START_TEST_RUN_RETRY_EXHAUSTED`, `START_TEST_RUN_DRAFT_PRS_NOT_ALLOWED`, `START_TEST_RUN_PERMISSIONS_BLOCK_TEST_BRANCH`, `START_TEST_RUN_NO_REQUIRED_STATUSES`, `START_TEST_RUN_CONFIG_NOT_FOUND`, `START_TEST_RUN_CONFIG_PARSING_FAILURE`, `START_TEST_RUN_CONFIG_BAD_VERSION`, `START_TEST_RUN_CONFIG_BAD_REQUIRED_STATUSES`, `START_TEST_RUN_CONFIG_MISSING_REQUIRED_STATUSES`, `START_TEST_RUN_INVALID_EVENT`, `PR_UPDATED_AT_MERGE_TIME`, `GITHUB_API_MERGE_PR_FAILED`, `GITHUB_API_DIRECT_MERGE_PR_FAILED`, `GITHUB_API_BRANCH_PROTECTION_UNMET`, `GITHUB_API_MERGE_ALREADY_IN_PROGRESS`, `GITHUB_API_RATE_LIMIT_EXCEEDED`, `GITHUB_API_REPEATED_SERVER_ERRORS`. **Why an entry was removed (`cancelled`)** — `USER_REQUESTED`, `TRUNK_ADMIN_REQUESTED`, `PR_CLOSED`, `PR_MERGED_INTO_OTHER_BRANCH`, `PR_PUSHED_TO`, `PR_BASE_BRANCH_CHANGED`, `PR_CONVERTED_TO_DRAFT`, `NOT_READY_TIMEOUT_EXPIRED`, `STACKED_PR_MEMBER_PUSHED_TO`, `STACKED_PR_MEMBER_CLOSED`, `STACKED_PR_MEMBER_MERGED`, `STACKED_PR_MEMBER_BASE_BRANCH_CHANGED`, `STACKED_PR_STACK_CHANGED`, `STACKED_PR_GROUP_CANCELLED_AT_MERGE_TIME`. **Why an entry merged (`merged`)** — `MERGE_GRAPH_MERGE`, `MERGE_GRAPH_DIRECT_MERGE`, `MANUAL_MERGE`. example: TEST_RUN_REQUIRED_STATUS_FAILED verificationRunId: type: string description: >- The verification run this transition concerns — present for `testing`, for `testsPassed`, and for `failed`/`pendingFailure` when the cause was a test. Read it with `GET /v2/merge-queue-verification-runs/{id}` for its checks and tested pull requests. For `reason: SUCCESSOR_TEST_RUN_PASSED` it is the successor's run rather than this entry's own. Omitted when the transition concerns no run. example: a1b2c3d4-e5f6-4718-9a0b-1c2d3e4f5061 actor: $ref: '#/components/schemas/TransitionActor' prerequisitePullRequestId: type: string description: >- For a `PREREQUISITE_*` reason, the pull request ahead of this one whose outcome forced this transition — always one of `pending.prerequisitePullRequests`, which lists every entry it was queued behind. Read it with `GET /v2/pull-requests/{id}`. Omitted otherwise. example: 0f8fad5b-d9cb-469f-a165-70867728950e notReady: $ref: '#/components/schemas/NotReadyTransitionDetails' pending: $ref: '#/components/schemas/PendingTransitionDetails' testsPassed: $ref: '#/components/schemas/TestsPassedTransitionDetails' pendingFailure: $ref: '#/components/schemas/PendingFailureTransitionDetails' failed: $ref: '#/components/schemas/FailedTransitionDetails' required: - pullRequestId - state - changedAt - reason description: >- One state change of a pull request's queue entry, and the evidence for it. Together these answer why an entry keeps being re-tested: `reason` gives the cause (a person, an API call, an upstream push, a failing entry ahead), `actor` names the person when one is recorded, `verificationRunId` links to the run that failed, and `prerequisitePullRequestId` names the pull request that blocked this one. `actor` is **absent** for engine- and machine-initiated transitions — that is a real answer, not a gap, and `reason` distinguishes them (`TESTS_RESTARTED_BY_USER` vs `TESTS_RESTARTED_BY_API_REQUEST` vs `BISECTION_REQUIRED`). At most one of `notReady`, `pending`, `testsPassed`, `pendingFailure` and `failed` is present, matching `state`, carrying that state's particulars: the priority an entry was submitted with, the entries it was queued behind, the batch that vouched for it, the checks that failed it, the branch-protection rules it did not meet, or the commit its merge conflict was traced to. `cancelled` and `merged` transitions carry nothing beyond `reason` and `actor`, and `testing` nothing beyond `verificationRunId`. ErrorCode: type: string enum: - AUTHENTICATION_REQUIRED - INVALID_TOKEN - INSUFFICIENT_PERMISSIONS - INTERNAL_ERROR - VALIDATION_FAILED - NOT_FOUND - INVALID_CURSOR - MERGE_QUEUE_NOT_FOUND - PR_ALREADY_ENQUEUED - PR_NOT_ENQUEUEABLE - UPSTREAM_ERROR - VERIFICATION_RUN_NOT_FOUND - PR_NOT_FOUND - REPOSITORY_NOT_FOUND - IMPACTED_TARGETS_UNSUPPORTED - QUEUE_ALREADY_EXISTS - QUEUE_HAS_ACTIVE_ENTRIES - MODE_CHANGE_IN_PROGRESS - PR_NOT_IN_ACTIVE_STATE - MERGE_QUEUE_NOT_CREATABLE - PR_TESTS_NOT_RESTARTABLE - ALLOWED_BOT_SUBMITTERS_FROZEN - ESTIMATE_NOT_ENABLED - PROVIDER_URL_NOT_FOUND - CI_HOST_UNSUPPORTED - CI_SCOPE_NOT_FOUND - CI_JOB_NOT_FOUND - CI_FAILURE_CLUSTER_NOT_FOUND - TEST_COLLECTION_NOT_FOUND - TEST_NOT_FOUND - TEST_UPLOAD_NOT_FOUND - TICKETING_NOT_CONFIGURED - TICKETING_CREDENTIALS_INVALID - TICKETING_SITE_REFUSED - TICKET_NOT_FOUND - TICKET_LINK_CONFLICT - TEST_ALREADY_LINKED - TICKET_FIELDS_REJECTED - TICKET_CONTENT_UNAVAILABLE - TICKETING_CREATE_REFUSED - RATE_LIMIT_EXCEEDED description: >- Stable machine-readable error identifier. Switch on this, never on `message`. A shipped code's meaning never changes, but **new codes may be added within v2** — treat an unrecognized code as a generic failure of its HTTP status rather than failing closed. example: INTERNAL_ERROR QueueEntryState: type: string enum: - notReady - pending - testing - testsPassed - merged - failed - cancelled - pendingFailure description: >- Where a pull request sits in its queue's lifecycle. | Value | Meaning | | --- | --- | | `notReady` | Enqueued but not yet eligible to test — a readiness condition is unmet (see `QueueEntry.readiness`). | | `pending` | Ready and waiting for a test slot, or waiting on an earlier entry. | | `testing` | A verification run is in flight for this entry. | | `testsPassed` | Verification succeeded; waiting to merge. | | `merged` | Terminal — merged into the target branch. | | `failed` | Terminal — verification or the merge itself failed. | | `cancelled` | Terminal — removed from the queue (dequeued, or cancelled by the engine). | | `pendingFailure` | A failure is expected because an entry ahead failed, but this entry has not been re-tested yet. Not terminal: it usually returns to `pending` or `testing`. | New members may be added within v2. example: testing TransitionActor: type: object properties: gitHubLogin: type: string description: The actor's GitHub login. example: octocat trunkUserId: type: string description: >- The actor's Trunk user id. Carried alongside the login because a GitHub login is renameable and so cannot be correlated against. example: 0f8fad5b-d9cb-469f-a165-70867728950e minProperties: 1 description: >- A recorded human cause of a state transition. At least one identifier is present. NotReadyTransitionDetails: type: object properties: priorityValue: type: integer description: Omitted when a named priority was used instead. example: 100 priorityName: type: string description: Omitted when a numeric priority was used instead. example: high allowBatching: type: boolean description: Whether the submission allowed the entry to be batched. example: true required: - allowBatching description: >- How the pull request was submitted: the priority and batching it was submitted with. Present on `notReady` transitions. PendingTransitionDetails: type: object properties: priorityValue: type: integer description: Omitted when a named priority was used instead. example: 100 priorityName: type: string description: Omitted when a numeric priority was used instead. example: high usedDefaultPriorityName: type: string description: >- The queue's default priority name, when no priority was supplied and the default applied. example: medium prerequisitePullRequests: type: array items: $ref: '#/components/schemas/TransitionPullRequestRef' maxItems: 10000 description: >- The entries ahead of this one that it was queued behind, oldest-enqueued first. Empty when nothing was ahead. required: - prerequisitePullRequests description: >- Where the pull request stood when it (re)entered the line. Present on `pending` transitions. TestsPassedTransitionDetails: type: object properties: batchSize: type: integer description: How many entries the verifying run tested together. example: 3 bisectionId: type: string description: >- Present when the pass was established by a bisection run rather than the batch's own. A correlation key only — equal across every `testsPassed` transition one bisection established — and not addressable by any endpoint. example: b7e2c1d0-4f3a-4c5b-9d8e-1a2b3c4d5e6f successorPullRequestId: type: string description: >- For `reason: SUCCESSOR_TEST_RUN_PASSED`, the entry behind this one whose passing run vouched for it (optimistic merging). `verificationRunId` then names that successor's run. example: 0f8fad5b-d9cb-469f-a165-70867728950e otherTestedPullRequests: type: array items: $ref: '#/components/schemas/TransitionPullRequestRef' maxItems: 10000 description: >- Every other entry that recorded a pass against this run. Usually that means the batch this entry was tested in, but it is NOT only that, and this list can exceed `batchSize - 1`: an entry that passed because this run vouched for it (its own transition reads `SUCCESSOR_TEST_RUN_PASSED`) is recorded against the run too and appears here. For the batch exactly, read `testedPullRequests` on the run itself (`GET /v2/merge-queue-verification-runs/{verificationRunId}`), which comes from what the run tested rather than from who passed on it; `successorPullRequestId` names the vouching relationship. The shape is v1's, and v2 serves it on every pass reason where v1 populated it only for a successor pass. waitingFor: type: array items: $ref: '#/components/schemas/TransitionPullRequestRef' maxItems: 10000 description: Entries ahead of this one that had to merge before it could. required: - batchSize - otherTestedPullRequests - waitingFor description: >- How the pull request came to pass verification. Present on `testsPassed` transitions; `verificationRunId` on the transition names the run. PendingFailureTransitionDetails: type: object properties: eventualFailureReason: type: string description: >- The `failed` reason this entry will conclude with, from the same vocabulary as `reason`. Omitted when not yet recorded. example: TEST_RUN_REQUIRED_STATUS_FAILED waitingFor: type: array items: $ref: '#/components/schemas/TransitionPullRequestRef' maxItems: 10000 description: >- The entries ahead of this one whose outcomes must land before the blame is settled. failureCausingChecks: type: array items: $ref: '#/components/schemas/FailureCausingCheck' maxItems: 10000 description: >- The required checks that failed. Populated when `eventualFailureReason` is `TEST_RUN_REQUIRED_STATUS_FAILED`. required: - waitingFor - failureCausingChecks description: >- Present on `pendingFailure` transitions: this pull request will fail, but the queue is waiting on the entries ahead of it to establish the blame. FailedTransitionDetails: type: object properties: apiFailureMessage: type: string description: The provider's own error message, for the `GITHUB_API_*` reasons. example: Base branch was modified. Review and try the merge again. failureCausingChecks: type: array items: $ref: '#/components/schemas/FailureCausingCheck' maxItems: 10000 description: >- The required checks that failed. Populated when `reason` is `TEST_RUN_REQUIRED_STATUS_FAILED`. blockReasons: type: array items: $ref: '#/components/schemas/MergeabilityReason' maxItems: 10000 description: >- The unmet branch-protection requirements, in the same vocabulary as `readiness.mergeabilityDetails`. Present when `reason` is `GITHUB_API_BRANCH_PROTECTION_UNMET` and the queue recorded them. conflictCulprit: $ref: '#/components/schemas/ConflictCulprit' required: - failureCausingChecks description: >- Why the pull request failed out of the queue. Present on `failed` transitions; which of its fields are populated depends on `reason`. TransitionPullRequestRef: type: object properties: pullRequestId: type: string description: Read it with `GET /v2/pull-requests/{id}`. example: 0f8fad5b-d9cb-469f-a165-70867728950e number: type: integer example: 4900 title: type: string example: Bump the widget limit url: type: string description: Omitted when Trunk has not yet indexed the provider URL. example: https://github.com/acme/widgets/pull/4900 state: allOf: - $ref: '#/components/schemas/QueueEntryState' - description: >- That entry's queue state **now**, not at the time of this transition. required: - pullRequestId - number - title - state description: >- Another queue entry a transition refers to — one ahead of this entry, a batch-mate, or a conflict culprit — resolved to its pull request. FailureCausingCheck: type: object properties: name: type: string description: The check's name, as it appears on the pull request. example: Test (rust) url: type: string description: A link to the failing check, when one was recorded. example: https://github.com/acme/widgets/runs/31245987 conclusion: type: string description: >- Why the check counted as failed, in SCREAMING_SNAKE_CASE. A provider check run contributes its conclusion (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ACTION_REQUIRED`); a commit status contributes its state (`FAILURE`, `ERROR`). Omitted on runs recorded before it was captured. example: FAILURE required: - name description: >- A required check whose failure failed a verification run. Names the check directly, so a consumer need not fetch the run to learn what broke. MergeabilityReason: type: object properties: code: $ref: '#/components/schemas/MergeabilityReasonCode' message: type: string description: >- Human-readable explanation, for display. Machines should branch on `code`, not this string. example: needs 1 more approving review have: type: integer minimum: 0 description: '`reviewRequired` only: approving reviews currently present.' example: 0 need: type: integer minimum: 0 description: '`reviewRequired` only: approving reviews required.' example: 1 check: type: string description: '`awaitingCheck` / `failingCheck` only: the required check''s name.' example: build ontoPrNumber: type: integer minimum: 0 description: >- `stackNeedsRebase` only: the number of the pull request this branch must be rebased onto. example: 3 required: - code - message description: One structured reason behind a `notMergeable` verdict. ConflictCulprit: type: object properties: kind: $ref: '#/components/schemas/ConflictCulpritKind' sha: type: string description: The commit the conflict was traced to. example: 9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f pullRequestId: type: string description: >- The culprit pull request, when it is one Trunk indexed. Omitted for a `baseBranch` culprit. example: 0f8fad5b-d9cb-469f-a165-70867728950e number: type: integer example: 4899 url: type: string example: https://github.com/acme/widgets/pull/4899 required: - kind - sha description: >- The earlier commit a merge conflict was traced to. The queue identifies it asynchronously after the failure, so it is absent until that investigation finishes, and permanently absent when no single commit was to blame. MergeabilityReasonCode: type: string enum: - conflict - behind - draft - closed - pending - awaitingCheck - failingCheck - reviewRequired - changesRequested - stackNeedsRebase - other description: >- Why the pull request is not mergeable. `behind`, `pending`, and `awaitingCheck` resolve without author action (Trunk updates the branch; GitHub is still computing; a required check is still running); the rest need the author to act. `stackNeedsRebase` means a PR in the middle of this GitHub stack was pushed to without rebasing the ones above it. `other` is a block Trunk could not attribute to a specific rule. example: reviewRequired ConflictCulpritKind: type: string enum: - queuePullRequest - baseBranch - stackedPullRequest description: >- What the conflicting commit belongs to. `queuePullRequest` — an entry ahead in the queue. `baseBranch` — the target branch itself advanced. `stackedPullRequest` — a member of a stacked pull request. securitySchemes: apiKey: type: http scheme: bearer description: >- An API key, sent as `Authorization: Bearer `. An organization admin creates one in the Trunk app under **Settings → Developer → API Keys** and chooses the merge-queue permissions it holds; a key with none can read merge queues but change nothing. Those permissions scope merge queue only: every key can use the Flaky Tests and Dynamic CI endpoints, including their writes, whatever permissions it holds. trunkToken: type: apiKey in: header name: x-trunk-token description: >- A short-lived first-party token, sent in the `x-trunk-token` header. The `trunk` CLI sends one after `trunk auth login`, and the `trunk-io/login` action obtains one for a GitHub Actions run. **A token from a GitHub Actions run can only upload impacted targets** (`PUT /v2/impacted-targets`), for the repository the run belongs to; every other endpoint refuses it. ````