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

# Re-run a pull request's failed checks

> Requires the **Merge and cancel PRs** permission. Re-runs the failed jobs of the GitHub Actions workflows behind the failed required checks, and keeps the pull request's place in the queue: it stays in `pendingFailure` until the re-run starts or `rerun.until` passes, whichever is first. If the re-run has not started by then, the pull request fails as it would have without the request. Only possible while the entry is in `pendingFailure` on a queue that keeps failed test runs; every refusal is a `422` with its own code.

`mode` is required. **Disruptive** with `mode: now`: it stops the jobs still running in the failed checks' workflows. `mode: wait` lets them finish first. `now` on a request that is waiting switches it to `now` (`rerun.switchedToNow`). `Idempotency-Key` is not honored, but a repeat with the same `mode` is safe: it answers `rerun.alreadyHeld` and changes nothing.



## OpenAPI

````yaml /openapi-v2.json post /v2/pull-requests/{id}/rerun-failed-checks
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 <key>`. An
    organization admin creates one in the Trunk app under **Settings → Developer
    → API Keys**, and chooses the permissions it holds. A key with no
    permissions can read merge queues but change nothing in them. Each write's
    description names the permission it needs, if any. Permissions cover merge
    queues and test-result uploads, including the quarantine lookups a CI run
    makes before it uploads; any key can call the other Flaky Tests and Dynamic
    CI endpoints, including their writes.


    A short-lived token in the `x-trunk-token` header is what Trunk's own tools
    send, such as the `trunk` CLI after `trunk auth login`. Your own
    integrations should use an API key.


    A GitHub Actions job can upload and read 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`, by `GET
    /v2/pull-requests/{id}/impacted-targets` and, on a fork pull request, by the
    Flaky Tests CLI endpoints. It works only for the run's own repository. On a
    fork pull request it works only for that pull request, and the upload works
    only for the pull request's head sha.


    ## Errors


    Errors from the API are an `ErrorResponse`: `{ "error": { "code", "message"
    } }`. Switch on `code`, which is stable; `message` is prose and may change
    at any time.


    Some responses don't have this shape. Trunk's edge answers `401`, `403` for
    some credential problems (including a request with no credential), `429`,
    and gateway errors such as `503` before the request reaches the API. The API
    itself answers `413` for a body over 512 KB and `504` for a request that
    runs past its time limit (usually 5 seconds), both as plain text. Read
    `error.code` only when the body is JSON with an `error` object, and
    otherwise branch on the status code.


    **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 from the API carries an `X-Request-Id` header; edge responses
    may not. Quote it in support requests.


    ## Rate limiting


    Most requests share one limit per organization (currently 100 requests per
    second), across every API key, user, and CLI session in it. Some requests
    have limits of their own and don't count toward it: `GET` requests on paths
    that start with `/v2/pull-requests`, `/v2/ci-jobs`, `/v2/ci-workflow-runs`,
    or `/v2/ci-failure-clusters` (5 per second per API key or user); the merge
    queue metrics endpoints (5 per second per organization); every request from
    a GitHub Actions login, which includes impacted-target uploads and reads and
    the Flaky Tests CLI endpoints on a fork pull request (10 per second per
    repository, and separately for its fork pull requests; the other limits in
    this list do not apply to it); test-result uploads (1000 per second per
    organization) and quarantine lookups (250 per second per organization).
    Exceeding a limit returns `429`; retry with backoff. The limit is enforced
    at the edge, which does not yet wrap its `429` in the `ErrorResponse`
    envelope or send `Retry-After`, so 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. `PUT
    /v2/impacted-targets` accepts GitHub and GitLab repositories. A GitHub
    Actions login (the `trunk-io/login` action, or `trunk auth login
    --github-actions`) uploads only for its own GitHub repository. 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
  - name: detectionEvents
    x-group: Detection Events
  - name: monitors
    x-group: Monitors
  - name: monitorTests
    x-group: Monitor Tests
paths:
  /v2/pull-requests/{id}/rerun-failed-checks:
    post:
      tags:
        - pullRequests
      summary: Re-run a pull request's failed checks
      description: >-
        Requires the **Merge and cancel PRs** permission. Re-runs the failed
        jobs of the GitHub Actions workflows behind the failed required checks,
        and keeps the pull request's place in the queue: it stays in
        `pendingFailure` until the re-run starts or `rerun.until` passes,
        whichever is first. If the re-run has not started by then, the pull
        request fails as it would have without the request. Only possible while
        the entry is in `pendingFailure` on a queue that keeps failed test runs;
        every refusal is a `422` with its own code.


        `mode` is required. **Disruptive** with `mode: now`: it stops the jobs
        still running in the failed checks' workflows. `mode: wait` lets them
        finish first. `now` on a request that is waiting switches it to `now`
        (`rerun.switchedToNow`). `Idempotency-Key` is not honored, but a repeat
        with the same `mode` is safe: it answers `rerun.alreadyHeld` and changes
        nothing.
      operationId: pullRequests.rerunFailedChecks
      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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RerunFailedChecksRequest'
      responses:
        '200':
          description: The pull request, and the re-run it is waiting for
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerunFailedChecksResult'
        '400':
          description: '`VALIDATION_FAILED`'
          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'
        '401':
          description: >-
            `AUTHENTICATION_REQUIRED` | `INVALID_TOKEN`. A malformed, expired,
            or deleted credential. Trunk's edge usually answers this before the
            request reaches the API, with a body that is not this envelope
            (`{"error": "unauthorized: invalid api key"}` for a bad API key, or
            plain text for a bad `x-trunk-token`), so branch on the status. A
            request with no credential at all gets `403` from the edge.
          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
        '403':
          description: '`INSUFFICIENT_PERMISSIONS`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                INSUFFICIENT_PERMISSIONS:
                  summary: INSUFFICIENT_PERMISSIONS
                  value:
                    error:
                      code: INSUFFICIENT_PERMISSIONS
                      message: >-
                        The supplied credential is missing the required
                        permission
        '404':
          description: '`PR_NOT_FOUND` | `MERGE_QUEUE_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
                MERGE_QUEUE_NOT_FOUND:
                  summary: MERGE_QUEUE_NOT_FOUND
                  value:
                    error:
                      code: MERGE_QUEUE_NOT_FOUND
                      message: Merge queue not found
        '409':
          description: '`PR_NOT_IN_ACTIVE_STATE`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PR_NOT_IN_ACTIVE_STATE:
                  summary: PR_NOT_IN_ACTIVE_STATE
                  value:
                    error:
                      code: PR_NOT_IN_ACTIVE_STATE
                      message: This pull request is not in an active queue state
        '422':
          description: >-
            `PR_RERUN_FEATURE_DISABLED` | `PR_RERUN_NOT_PENDING_FAILURE` |
            `PR_RERUN_QUEUE_DOES_NOT_KEEP_FAILED_RUNS` |
            `PR_RERUN_NOT_A_REQUIRED_CHECK_FAILURE` |
            `PR_RERUN_CHECK_NOT_RERUNNABLE` | `PR_RERUN_RUN_TORN_DOWN` |
            `PR_RERUN_HOLD_LIMIT_REACHED` | `PR_RERUN_FORGE_NOT_SUPPORTED`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PR_RERUN_FEATURE_DISABLED:
                  summary: PR_RERUN_FEATURE_DISABLED
                  value:
                    error:
                      code: PR_RERUN_FEATURE_DISABLED
                      message: >-
                        You cannot re-run failed checks from Trunk on this
                        queue.
                PR_RERUN_NOT_PENDING_FAILURE:
                  summary: PR_RERUN_NOT_PENDING_FAILURE
                  value:
                    error:
                      code: PR_RERUN_NOT_PENDING_FAILURE
                      message: You cannot re-run checks for this pull request now.
                PR_RERUN_QUEUE_DOES_NOT_KEEP_FAILED_RUNS:
                  summary: PR_RERUN_QUEUE_DOES_NOT_KEEP_FAILED_RUNS
                  value:
                    error:
                      code: PR_RERUN_QUEUE_DOES_NOT_KEEP_FAILED_RUNS
                      message: >-
                        This queue does not allow re-runs. A queue admin can
                        turn on "Allow Re-running Failed Checks".
                PR_RERUN_NOT_A_REQUIRED_CHECK_FAILURE:
                  summary: PR_RERUN_NOT_A_REQUIRED_CHECK_FAILURE
                  value:
                    error:
                      code: PR_RERUN_NOT_A_REQUIRED_CHECK_FAILURE
                      message: No required check failed. Use Restart tests.
                PR_RERUN_CHECK_NOT_RERUNNABLE:
                  summary: PR_RERUN_CHECK_NOT_RERUNNABLE
                  value:
                    error:
                      code: PR_RERUN_CHECK_NOT_RERUNNABLE
                      message: >-
                        Trunk can re-run only GitHub Actions checks. Re-run
                        `buildkite/ci` in its own CI, or use Restart tests.
                PR_RERUN_RUN_TORN_DOWN:
                  summary: PR_RERUN_RUN_TORN_DOWN
                  value:
                    error:
                      code: PR_RERUN_RUN_TORN_DOWN
                      message: These checks cannot be re-run now. Use Restart tests.
                PR_RERUN_HOLD_LIMIT_REACHED:
                  summary: PR_RERUN_HOLD_LIMIT_REACHED
                  value:
                    error:
                      code: PR_RERUN_HOLD_LIMIT_REACHED
                      message: >-
                        These checks were already re-run two times. Use Restart
                        tests.
                PR_RERUN_FORGE_NOT_SUPPORTED:
                  summary: PR_RERUN_FORGE_NOT_SUPPORTED
                  value:
                    error:
                      code: PR_RERUN_FORGE_NOT_SUPPORTED
                      message: >-
                        Trunk can re-run checks only for GitHub repositories.
                        Use Restart tests.
        '429':
          description: >-
            `RATE_LIMIT_EXCEEDED`. Trunk's edge answers this, and does not yet
            wrap it in the error envelope or send `Retry-After`: treat any `429`
            as rate limiting, whatever its body, and retry with backoff.
          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 with backoff
        '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
        '502':
          description: '`UPSTREAM_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UPSTREAM_ERROR:
                  summary: UPSTREAM_ERROR
                  value:
                    error:
                      code: UPSTREAM_ERROR
                      message: An upstream service did not respond
components:
  schemas:
    RerunFailedChecksRequest:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/RerunMode'
      required:
        - mode
      additionalProperties: false
      description: >-
        `mode` is required: `now` stops the jobs still running in the failed
        checks' workflows and re-runs them with the failed jobs, and `wait`
        re-runs the failed jobs once those workflows finish. `now` on a request
        that is waiting switches it to `now`. Send the body as
        `application/json`; a missing body, or one without `mode`, is a `400`.
    RerunFailedChecksResult:
      type: object
      properties:
        pullRequest:
          $ref: '#/components/schemas/PullRequest'
        rerun:
          $ref: '#/components/schemas/RerunHeld'
      required:
        - pullRequest
        - rerun
      description: The pull request after the request, and the re-run it is waiting for.
    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 error envelope. Every error this API itself returns has this shape,
        except a `413` for a body over 512 KB and a `504` for a request that
        runs past its time limit, which are plain text. Responses from Trunk's
        edge, such as a `401`, a `403` for a missing credential, a `429` or a
        `503`, can arrive before the request reaches the API and may not have
        it, so read `error.code` only when the body is JSON with an `error`
        object.
    RerunMode:
      type: string
      enum:
        - now
        - wait
      description: >-
        `now`: stop the jobs still running in the failed checks' workflows and
        re-run them with the failed jobs. `wait`: re-run the failed jobs once
        those workflows finish.
      example: now
    PullRequest:
      type: object
      properties:
        id:
          type: string
          example: 0f8fad5b-d9cb-469f-a165-70867728950e
        repositoryId:
          type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        number:
          type: integer
          example: 4901
        title:
          type: string
          example: 'feat: terminate /v2 at the gateway'
        branch:
          type: string
          example: phil/implement-remaining-apis
        sha:
          type: string
          description: >-
            The head commit of the pull request as Trunk last indexed it.
            Compare against a verification run's `testedPullRequests[].sha` to
            tell whether a run tested the current head or a superseded one — a
            mismatch means the branch moved after that run started.
          example: 9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f
        baseBranch:
          type: string
          description: >-
            The branch this pull request targets. Must match the queue's
            `targetBranch` to be enqueueable — `readiness.doesBaseBranchMatch`
            reports that check.
          example: main
        author:
          type: string
          example: octocat
        url:
          type: string
          description: Omitted until the provider sync has populated it.
          example: https://github.com/acme/widgets/pull/4901
        state:
          $ref: '#/components/schemas/PullRequestState'
        isCurrentlySubmittedToQueue:
          type: boolean
          description: True when this pull request's queue entry is non-terminal.
          example: true
        queueEntry:
          $ref: '#/components/schemas/QueueEntry'
        createdAt:
          type: string
          format: date-time
          example: '2026-07-28T10:55:00.000Z'
        htmlUrl:
          type: string
          description: >-
            The pull request's page in the Trunk web app. Absent when the
            repository has no keyed organization.
          example: https://app.trunk.io/acme/pull/4901?repo=1a2b3c4d
        viewerIsAuthor:
          type: boolean
          description: >-
            Whether the authenticated user authored this pull request. Provided
            on the queue pull-request list (`GET
            /merge-queues/{id}/pull-requests`); absent elsewhere and when the
            caller is not a signed-in user.
          example: true
        ci:
          anyOf:
            - $ref: '#/components/schemas/PullRequestCi'
            - type: 'null'
          description: >-
            CI on the head commit. Null when the repository has no CI data.
            Absent from lists, from a lookup of more than one pull request, and
            when the CI read failed.
      required:
        - id
        - repositoryId
        - number
        - title
        - branch
        - sha
        - baseBranch
        - author
        - isCurrentlySubmittedToQueue
        - createdAt
      description: >-
        A pull request Trunk has indexed. There is no nested repository object —
        resolve `repositoryId` with `GET /v2/repositories/{id}`.
    RerunHeld:
      type: object
      properties:
        until:
          type: string
          format: date-time
          description: >-
            When the queue stops waiting for the re-run to start. If it has not
            started by then, the pull request fails.
          example: '2026-07-28T11:40:00.000Z'
        alreadyHeld:
          type: boolean
          description: >-
            True when an earlier request for these checks was already waiting,
            so this request changed nothing.
          example: false
        switchedToNow:
          type: boolean
          description: True when this request switched a waiting `wait` request to `now`.
          example: false
        checks:
          type: array
          items:
            type: string
          maxItems: 10000
          description: The failed required checks being re-run.
          example:
            - build
        requestedBy:
          $ref: '#/components/schemas/TransitionActor'
      required:
        - until
        - alreadyHeld
        - switchedToNow
        - checks
      description: >-
        The accepted re-run request. `requestedBy` names the earlier requester
        when `alreadyHeld` is true and a user made that request.
    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
        - IMPACTED_TARGETS_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
        - PR_RERUN_FEATURE_DISABLED
        - PR_RERUN_NOT_PENDING_FAILURE
        - PR_RERUN_QUEUE_DOES_NOT_KEEP_FAILED_RUNS
        - PR_RERUN_NOT_A_REQUIRED_CHECK_FAILURE
        - PR_RERUN_CHECK_NOT_RERUNNABLE
        - PR_RERUN_RUN_TORN_DOWN
        - PR_RERUN_HOLD_LIMIT_REACHED
        - PR_RERUN_FORGE_NOT_SUPPORTED
        - PROVIDER_URL_NOT_FOUND
        - CI_HOST_UNSUPPORTED
        - CI_JOB_NOT_FOUND
        - CI_FAILURE_CLUSTER_NOT_FOUND
        - TEST_COLLECTION_NOT_FOUND
        - TEST_NOT_FOUND
        - TEST_UPLOAD_NOT_FOUND
        - MONITOR_NOT_FOUND
        - MONITOR_LIMIT_EXCEEDED
        - MONITOR_NOT_ACTIVE
        - OUT_OF_RANGE
        - TEST_UNAVAILABLE
        - TICKETING_NOT_CONFIGURED
        - TICKETING_CREDENTIALS_INVALID
        - TICKETING_SITE_REFUSED
        - TICKET_NOT_FOUND
        - TICKET_NOT_LINKED
        - 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
    PullRequestState:
      type: string
      enum:
        - open
        - closed
        - merged
      description: >-
        The pull request's state at the provider, as Trunk last indexed it — not
        its queue state, which is `QueueEntry.state`.
      example: open
    QueueEntry:
      type: object
      properties:
        id:
          type: string
          description: >-
            This membership's own id — the merge item, not the pull request. A
            pull request has at most one entry at a time, and an ordinary
            resubmission after a cancellation reuses it. It is not a permanent
            handle on the pull request, though: an entry the queue tears down is
            replaced, so a pull request whose base branch moves it to a
            different queue gets a new id on its next submission.
          example: 6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f
        mergeQueueId:
          type: string
          example: xK9mP2nQ
        state:
          $ref: '#/components/schemas/QueueEntryState'
        stateChangedAt:
          type: string
          format: date-time
          description: >-
            When the entry entered its current `state` — the newest `changedAt`
            in its queue-entry history, or `createdAt` before any transition was
            recorded.
          example: '2026-07-28T11:40:02.000Z'
        priorityValue:
          type: integer
          description: >-
            The entry's numeric priority. 0 means skip the line. A submit body
            carries this OR `priorityName`, never both — but the queue usually
            resolves a submitted name to a value, so a read normally returns
            both and they agree. Either may still be absent on its own: some
            entries carry a value the queue never named, and some a name it
            never resolved.
          example: 100
        priorityName:
          type: string
          description: >-
            The entry's named priority. A submit body carries this OR
            `priorityValue`, never both; a read normally returns both, since the
            queue stores the value it resolved this name to. Either may still be
            absent on its own — do not infer one from the presence of the other.
          example: high
        usedDefaultPriorityName:
          type: string
          description: >-
            The default priority name the engine applied because a submission
            supplied no priority. It records this when the entry enters the
            queue proper, not at submission, and a resubmission does not clear
            it — so an entry can carry the value from an earlier cycle,
            including beside an explicitly-supplied `priorityValue`. A `PATCH
            /v2/pull-requests/{id}/queue-entry` on an already-enqueued entry
            does clear it, because that patch resupplies the priority
            explicitly.
          example: medium
        skipsTheLine:
          type: boolean
          description: >-
            Read-only — derived from `priorityValue === 0`. To set it, send
            `priorityValue: 0`.
          example: false
        allowBatching:
          type: boolean
          description: >-
            Whether this entry may be verified in a batch with others. The
            queue's own `config.allowBatching` is the ceiling — an entry cannot
            batch when the queue forbids it.
          example: true
        direct:
          type: boolean
          description: >-
            Whether the entry was sent directly to the queue past an unmet
            readiness condition (`direct` on submit or on `PATCH
            /v2/pull-requests/{id}/queue-entry`). It did not skip the queue's
            own tests.
          example: false
        mergeMethod:
          anyOf:
            - $ref: '#/components/schemas/MergeMethod'
            - type: 'null'
          description: >-
            The merge method this pull request chose, on submit or on `PATCH
            /v2/pull-requests/{id}/queue-entry`. `null` means the queue's merge
            method applies. A choice applies only while the queue lets pull
            requests choose their own merge method; otherwise the queue's is
            used.
          example: rebase
        verifiedByVerificationRunId:
          type: string
          description: >-
            The verification run whose pass the queue merged this entry on.
            Present only for an entry the queue itself merged straight out of
            `testsPassed`; absent for a force merge, a direct merge, a merge
            made on the provider, or any unmerged entry. For an optimistically
            merged entry it is the successor's run — the one that vouched. Read
            it with `GET /v2/merge-queue-verification-runs/{id}`.
          example: a1b2c3d4-e5f6-4718-9a0b-1c2d3e4f5061
        readiness:
          $ref: '#/components/schemas/Readiness'
        createdAt:
          type: string
          format: date-time
          description: >-
            When this queue entry was created — the pull request's FIRST
            submission. The entry is reused across resubmissions (a cancelled or
            failed pull request submitted again keeps it), so on a pull request
            that took several trips this is not the start of the trip that
            merged. For that, read the oldest `notReady` transition of the trip
            you care about from `GET
            /v2/pull-requests/{id}/queue-entry-history`.
          example: '2026-07-28T11:02:31.000Z'
        updatedAt:
          type: string
          format: date-time
          description: >-
            When the entry row last changed, including an attribute-only write
            (priority, batching) that records no transition. For the last state
            change specifically, read `stateChangedAt`.
          example: '2026-07-28T11:40:02.000Z'
      required:
        - id
        - mergeQueueId
        - state
        - stateChangedAt
        - skipsTheLine
        - allowBatching
        - direct
        - mergeMethod
        - readiness
        - createdAt
        - updatedAt
      description: >-
        A pull request's queue membership. A pull request has at most one at a
        time, and resubmitting it to the same queue reuses this record. An entry
        the queue tears down is replaced, so a later submission can carry a
        different `id` and `mergeQueueId`.
    PullRequestCi:
      type: object
      properties:
        headSha:
          type: string
          description: 'The commit the counts describe: the pull request''s head.'
          example: a0de7a77e8d758a346f83ed19209a5a25814bb17
        observedAt:
          type: string
          format: date-time
          example: '2026-09-29T15:12:25.000Z'
        pollAfterSeconds:
          type:
            - integer
            - 'null'
          description: >-
            When to read again: 10 while a job is queued or running, 30 while a
            failure's analysis is on its way, null when nothing on this commit
            will change.
          example: 10
        jobs:
          $ref: '#/components/schemas/CiJobCounts'
        jobsUrl:
          type: string
          description: >-
            The jobs on `headSha`: `GET /v2/ci-jobs`, already filtered.
            Root-relative: resolve it against the host you called.
          example: >-
            /v2/ci-jobs?pullRequestId=0f8fad5b-d9cb-469f-a165-70867728950e&commitSha=a0de7a77e8d758a346f83ed19209a5a25814bb17
        workflowRunsUrl:
          type: string
          description: >-
            The workflow runs on `headSha`: `GET /v2/ci-workflow-runs`, already
            filtered. Root-relative, like `jobsUrl`.
          example: >-
            /v2/ci-workflow-runs?pullRequestId=0f8fad5b-d9cb-469f-a165-70867728950e&commitSha=a0de7a77e8d758a346f83ed19209a5a25814bb17
      required:
        - headSha
        - observedAt
        - pollAfterSeconds
        - jobs
        - jobsUrl
        - workflowRunsUrl
      description: >-
        CI on the pull request's head commit, counted. The lists are one request
        away through `jobsUrl` and `workflowRunsUrl`.
    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.
    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` | This entry's tests failed, and the queue is holding
        it to learn whether the failure is its own: it waits for the entries
        ahead of it to finish, and a passing run behind it can vouch for it. Not
        terminal: it can still pass and merge, return to `pending` or `testing`,
        or end `failed`. |


        New members may be added within v2.
      example: testing
    MergeMethod:
      type: string
      enum:
        - mergeCommit
        - squash
        - rebase
      description: >-
        How the queue writes a passing entry onto the target branch: a merge
        commit, a single squashed commit, or replayed commits. Must be permitted
        by the repository's own provider settings.
      example: squash
    Readiness:
      type: object
      properties:
        requiresImpactedTargets:
          type: boolean
          description: >-
            Whether this queue gates the entry on an impacted-target upload.
            When true and `hasImpactedTargets` is false, the entry stays
            `notReady` until CI uploads them (`impactedTargets.upload`).
          example: true
        hasImpactedTargets:
          type: boolean
          description: >-
            Whether impacted targets are uploaded for the entry's commit — for a
            stacked pull request, for every pull request its queued stack covers
            — or not needed (queue mode, or a pull request predating the queue's
            switch to graph mode). ABSENT, not false, in two cases: on a list
            read (which includes a coordinates lookup addressed by more than one
            `number`), and on the response to a write whose post-write lookup
            failed. Absence means 'not answered here' — never 'no targets'.
          example: true
        doesBaseBranchMatch:
          type: boolean
          description: >-
            Whether the pull request's `baseBranch` still equals the queue's
            `targetBranch`. False means it was retargeted after being enqueued
            and cannot merge through this queue.
          example: true
        mergeability:
          $ref: '#/components/schemas/Mergeability'
        mergeabilityDetails:
          $ref: '#/components/schemas/MergeabilityDetails'
      required:
        - requiresImpactedTargets
        - doesBaseBranchMatch
        - mergeability
      description: >-
        Whether the pull request currently satisfies what the queue needs of it.
        Recomputed at read time, NOT a snapshot of the entry's state change — so
        a `merged` entry can report `notMergeable` (its branch has since moved,
        or the provider now says so), which is a fact about the pull request
        today rather than a contradiction of the merge.
    CiJobCounts:
      type: object
      properties:
        total:
          type: integer
          example: 209
        queued:
          type: integer
          example: 0
        running:
          type: integer
          example: 0
        passed:
          type: integer
          example: 110
        failed:
          type: integer
          description: Conclusion `failure` or `timedOut`.
          example: 2
        cancelled:
          type: integer
          example: 0
        skipped:
          type: integer
          example: 97
        abandoned:
          type: integer
          example: 0
      required:
        - total
        - queued
        - running
        - passed
        - failed
        - cancelled
        - skipped
        - abandoned
      description: >-
        The latest attempt of every job, counted. The fields other than `total`
        sum to `total`.
    Mergeability:
      type: string
      enum:
        - mergeable
        - notMergeable
        - inProgress
        - unspecified
      description: >-
        The provider's view of whether the pull request can merge. `unspecified`
        means the provider has not reported one.
      example: mergeable
    MergeabilityDetails:
      type: object
      properties:
        provider:
          type: string
          enum:
            - github
          example: github
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/MergeabilityReason'
          maxItems: 100
          description: The reasons the provider is blocking the merge.
          example:
            - code: reviewRequired
              message: needs 1 more approving review
              have: 0
              need: 1
            - code: other
              message: >-
                the commit author email rule in ruleset `Acme policy` may not be
                satisfied
              ruleType: commit_author_email_pattern
              rulesetName: Acme policy
              rulesetUrl: https://github.com/acme/widgets/rules/42
      required:
        - provider
        - reasons
      description: >-
        Present only when Trunk recorded structured reasons for a `notMergeable`
        verdict — absent otherwise (a repo Trunk has not enriched, or an entry
        past the not-ready window). Absence never means the pull request is
        mergeable; fall back to `mergeability`.
    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
        ruleType:
          type: string
          description: >-
            `other` only: the type of the ruleset rule that may be blocking the
            merge, as GitHub names it (for example
            `commit_author_email_pattern`). Open-ended: a rule type GitHub adds
            later passes through unchanged.
          example: commit_author_email_pattern
        rulesetName:
          type: string
          description: '`other` only: the name of the ruleset that holds the rule.'
          example: Acme policy
        rulesetUrl:
          type: string
          description: >-
            `other` only: GitHub's page for the ruleset. Present only when it is
            an `https://github.com` URL.
          example: https://github.com/acme/widgets/rules/42
      required:
        - code
        - message
      description: One structured reason behind a `notMergeable` verdict.
    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 any other block; when Trunk can name the ruleset rule behind
        it, `ruleType`, `rulesetName` and `rulesetUrl` say which, and `message`
        names it.
      example: reviewRequired
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key, sent as `Authorization: Bearer <key>`. An organization admin
        creates one in the Trunk app under **Settings → Developer → API Keys**
        and chooses the permissions it holds. A key with none can read merge
        queues but change nothing in them. Permissions cover merge queues and
        test-result uploads, including the quarantine lookups a CI run makes
        before it uploads; any key can call the other Flaky Tests and Dynamic CI
        endpoints, including their writes.
    trunkToken:
      type: apiKey
      in: header
      name: x-trunk-token
      description: >-
        A short-lived token that Trunk's own tools send in the `x-trunk-token`
        header: the `trunk` CLI after `trunk auth login`, and the
        `trunk-io/login` action in a GitHub Actions run. Your own integrations
        should use an API key instead. Never send `Authorization` and
        `x-trunk-token` on the same request.


        **A token from a GitHub Actions run can only upload and read impacted
        targets** (`PUT /v2/impacted-targets` and `GET
        /v2/pull-requests/{id}/impacted-targets`), for the repository the run
        belongs to. On a pull request from a fork it can also call the Flaky
        Tests CLI endpoints. Every other endpoint refuses it.

````