> ## 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 and search tests

> Lists tests, by default across every test collection in your organization — pass `testCollectionId` to narrow to one. Each row carries the `id` to pass to the per-test endpoints.

`q` searches name, file, class and parent as case-insensitive substrings. Several words are separate requirements, not a phrase — `q=flaky slow` returns tests matching both, in any position. It also accepts per-field qualifiers mixed freely with those words: `q=file:checkout flaky class:PaymentTest`. Qualifier keys are case-sensitive, and an unrecognized prefix is treated as literal text rather than guessed at.

Rows omit `quarantineOverride`, `activeMonitors`, `manualFlag`, `firstSeenAt` and `lastFailureAt` — fetch a single test for those.



## OpenAPI

````yaml /openapi-v2.json get /v2/tests
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 new key starts with no
    permissions: it can read merge queues but change nothing in them, and it
    cannot get a Dynamic CI plan. Each endpoint that needs a permission names it
    in its description; the Dynamic CI plan endpoints need **Generate Dynamic CI
    plans**.


    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/tests:
    get:
      tags:
        - tests
      summary: List and search tests
      description: >-
        Lists tests, by default across every test collection in your
        organization — pass `testCollectionId` to narrow to one. Each row
        carries the `id` to pass to the per-test endpoints.


        `q` searches name, file, class and parent as case-insensitive
        substrings. Several words are separate requirements, not a phrase —
        `q=flaky slow` returns tests matching both, in any position. It also
        accepts per-field qualifiers mixed freely with those words:
        `q=file:checkout flaky class:PaymentTest`. Qualifier keys are
        case-sensitive, and an unrecognized prefix is treated as literal text
        rather than guessed at.


        Rows omit `quarantineOverride`, `activeMonitors`, `manualFlag`,
        `firstSeenAt` and `lastFailureAt` — fetch a single test for those.
      operationId: tests.list
      parameters:
        - 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
            minLength: 1
            description: >-
              Narrow to one collection, by its id. Omitted searches every
              collection in your organization.
            example: aB3xY9kQ
          required: false
          description: >-
            Narrow to one collection, by its id. Omitted searches every
            collection in your organization.
          name: testCollectionId
          in: query
        - schema:
            type: string
            minLength: 1
            description: 'Comma-separated statuses to include: `healthy`, `flaky`, `broken`.'
            example: flaky,broken
          required: false
          description: 'Comma-separated statuses to include: `healthy`, `flaky`, `broken`.'
          name: status
          in: query
        - schema:
            type: string
            minLength: 1
            description: >-
              Free-text search, with optional `file:` / `class:` / `parent:` /
              `name:` qualifiers.
            example: file:checkout flaky
          required: false
          description: >-
            Free-text search, with optional `file:` / `class:` / `parent:` /
            `name:` qualifiers.
          name: q
          in: query
        - schema:
            type: string
            minLength: 1
            description: Substring match on the test's file path.
            example: src/payments
          required: false
          description: Substring match on the test's file path.
          name: file
          in: query
        - schema:
            type: string
            minLength: 1
            description: Exact match on one of the test's code owners.
            example: '@acme/platform'
          required: false
          description: Exact match on one of the test's code owners.
          name: owner
          in: query
        - schema:
            type: string
            minLength: 1
            description: Exact match on the test's variant.
            example: ubuntu-22.04
          required: false
          description: Exact match on the test's variant.
          name: variant
          in: query
        - schema:
            type: string
            enum:
              - metrics
            description: >-
              Set to `metrics` to embed each test's metrics for `period` in the
              same response, instead of fetching them per test.
            example: metrics
          required: false
          description: >-
            Set to `metrics` to embed each test's metrics for `period` in the
            same response, instead of fetching them per test.
          name: include
          in: query
        - schema:
            type: string
            minLength: 1
            description: >-
              Only tests carrying this label, by name. Matched exactly,
              including case, since two labels may differ only in case. An
              unknown name returns an empty page, not an error.
            example: slow-on-prs
          required: false
          description: >-
            Only tests carrying this label, by name. Matched exactly, including
            case, since two labels may differ only in case. An unknown name
            returns an empty page, not an error.
          name: label
          in: query
        - schema:
            type: string
            minLength: 1
            description: >-
              Only tests currently linked to this ticket, by its Trunk id
              (`ticket.id` on a test). Spans every collection unless
              `testCollectionId` narrows it. An unknown id returns an empty
              page, not an error. Cannot be combined with `ticketKey`.
            example: 5b0e8f8a-1c2d-4e3f-8a9b-0c1d2e3f4a5b
          required: false
          description: >-
            Only tests currently linked to this ticket, by its Trunk id
            (`ticket.id` on a test). Spans every collection unless
            `testCollectionId` narrows it. An unknown id returns an empty page,
            not an error. Cannot be combined with `ticketKey`.
          name: ticketId
          in: query
        - schema:
            type: string
            minLength: 1
            description: >-
              Only tests currently linked to the ticket with this provider key
              or URL. A convenience: a key can change (a Jira issue moved
              between projects) and two connections can share one, so prefer
              `ticketId`, and pass `integrationId` to narrow to one connection.
              An unknown key returns an empty page.
            example: TRUNK-12345
          required: false
          description: >-
            Only tests currently linked to the ticket with this provider key or
            URL. A convenience: a key can change (a Jira issue moved between
            projects) and two connections can share one, so prefer `ticketId`,
            and pass `integrationId` to narrow to one connection. An unknown key
            returns an empty page.
          name: ticketKey
          in: query
        - schema:
            type: string
            minLength: 1
            description: >-
              The ticketing connection `ticketKey` is looked up in. Only valid
              with `ticketKey`.
            example: 6c1f9a9b-2d3e-4f40-9b0c-1d2e3f4a5b6c
          required: false
          description: >-
            The ticketing connection `ticketKey` is looked up in. Only valid
            with `ticketKey`.
          name: integrationId
          in: query
        - schema:
            type: string
            enum:
              - quarantined
              - notQuarantined
            description: >-
              Filter on effective quarantine state, derived from the test's
              status, its collection's quarantine settings and any per-test
              override.
            example: quarantined
          required: false
          description: >-
            Filter on effective quarantine state, derived from the test's
            status, its collection's quarantine settings and any per-test
            override.
          name: quarantineState
          in: query
        - schema:
            type: string
            enum:
              - alwaysQuarantine
              - neverQuarantine
              - any
            description: >-
              Only tests with a quarantine override, as set by `POST
              /v2/tests/{testId}/quarantine`: `alwaysQuarantine` or
              `neverQuarantine` for one mode, `any` for either. Matches the mode
              of a test's `quarantineOverride`, so a cleared override matches
              nothing. It filters on the override alone, whether or not the
              test's collection has quarantining turned on; combine it with
              `quarantineState` for the effective state.
            example: neverQuarantine
          required: false
          description: >-
            Only tests with a quarantine override, as set by `POST
            /v2/tests/{testId}/quarantine`: `alwaysQuarantine` or
            `neverQuarantine` for one mode, `any` for either. Matches the mode
            of a test's `quarantineOverride`, so a cleared override matches
            nothing. It filters on the override alone, whether or not the test's
            collection has quarantining turned on; combine it with
            `quarantineState` for the effective state.
          name: quarantineOverride
          in: query
        - schema:
            type: boolean
            description: >-
              Filter on whether the manual 'flag as flaky' mark is currently
              set.
            example: true
          required: false
          description: Filter on whether the manual 'flag as flaky' mark is currently set.
          name: markedFlaky
          in: query
        - schema:
            type: boolean
            description: >-
              Only tests that first became flaky inside `period`. Requires
              `period`.
            example: true
          required: false
          description: >-
            Only tests that first became flaky inside `period`. Requires
            `period`.
          name: newlyFlaky
          in: query
        - schema:
            type: string
            enum:
              - 1d
              - 7d
              - 14d
              - 30d
            description: >-
              Metrics window for `include=metrics`, any metric `sort`, and
              `newlyFlaky`. Required by each of them.
            example: 7d
          required: false
          description: >-
            Metrics window for `include=metrics`, any metric `sort`, and
            `newlyFlaky`. Required by each of them.
          name: period
          in: query
        - schema:
            type: string
            enum:
              - name
              - failureRate
              - durationP95
              - prsImpacted
              - lastRunAt
              - lastFailureAt
            default: name
            description: >-
              Field to sort by. A metric sort requires `period`, and excludes
              tests with no comparable value in it — no runs at all for most
              metrics, and additionally no failure for `lastFailureAt`.
          required: false
          description: >-
            Field to sort by. A metric sort requires `period`, and excludes
            tests with no comparable value in it — no runs at all for most
            metrics, and additionally no failure for `lastFailureAt`.
          name: sort
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: >-
              Sort direction. Defaults per sort: ascending for `name`,
              descending for every metric sort, which order worst-first.
          required: false
          description: >-
            Sort direction. Defaults per sort: ascending for `name`, descending
            for every metric sort, which order worst-first.
          name: direction
          in: query
      responses:
        '200':
          description: A page of tests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestList'
        '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`. 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
        '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
components:
  schemas:
    TestList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TestSummary'
          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 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.
    TestSummary:
      type: object
      properties:
        id:
          type: string
          description: >-
            The test's globally unique id. Stable across repos and collections,
            and safe to store.
          example: bfeebcf4-0000-8000-8000-000000000001
        testCollectionId:
          type: string
          description: The owning collection's id.
          example: aB3xY9kQ
        repositoryId:
          type: string
          description: >-
            The repository the test was uploaded for. Resolve with `GET
            /v2/repositories/{id}`. Uploads made without a repository carry the
            nil UUID, which names no repository and does not resolve.
          example: 7a2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d
        name:
          type: string
          example: suite::test_case_name
        parentName:
          type: string
          example: Foo
        className:
          type: string
          example: FooSuite
        file:
          type: string
          example: src/foo.test.ts
        target:
          type: string
          description: The build target that ran the test, when one was reported.
          example: //src:foo_test
        variant:
          type: string
          example: ''
        crossVariantId:
          type:
            - string
            - 'null'
          description: Groups the same test across variants, when it has any.
          example: 5d4c3b2a-1f0e-4a1b-8c9d-0e1f2a3b4c5d
        codeowners:
          type: array
          items:
            type: string
          maxItems: 1000
          example:
            - '@team-a'
        status:
          $ref: '#/components/schemas/TestStatus'
        statusSince:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When `status` last changed — how long the test has been in its
            current state. Null for a test no monitor has ever classified.
          example: '2026-06-01T10:00:00.000Z'
        quarantineState:
          $ref: '#/components/schemas/QuarantineState'
        quarantinedSince:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the test's current quarantine began, as far as Trunk records
            it. Null exactly when `quarantineState` is `notQuarantined`. For a
            test quarantined by an `alwaysQuarantine` override, the time that
            override was set. For a test quarantined automatically, the later of
            `statusSince` and the last time an override on it was cleared.
            Changes to the collection's quarantine settings are not recorded per
            test, so this can be earlier than when quarantining was turned on
            for the collection.
          example: '2026-06-01T10:00:00.000Z'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
          maxItems: 100
        url:
          type: string
          format: uri
          description: The test's page in the Trunk web app.
          example: >-
            https://app.trunk.io/acme/flaky-tests/collections/aB3xY9kQ/tests/bfeebcf4-0000-8000-8000-000000000001
        ticket:
          anyOf:
            - $ref: '#/components/schemas/TicketSummary'
            - type: 'null'
          description: >-
            The ticket currently linked to this test, as Trunk last synced it,
            or null if none is linked.
        metrics:
          anyOf:
            - $ref: '#/components/schemas/TestMetrics'
            - type: 'null'
          description: >-
            Returned only when `include=metrics` is set. Null when the test had
            no runs in `period`.
      required:
        - id
        - testCollectionId
        - repositoryId
        - name
        - parentName
        - className
        - file
        - target
        - variant
        - crossVariantId
        - codeowners
        - status
        - statusSince
        - quarantineState
        - quarantinedSince
        - labels
        - url
        - ticket
    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
        - MERGE_QUEUE_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
    TestStatus:
      type: string
      enum:
        - healthy
        - flaky
        - broken
      description: >-
        A test's current composite status, reconciled across every active
        monitor.
      example: flaky
    QuarantineState:
      type: string
      enum:
        - quarantined
        - notQuarantined
      description: >-
        Whether the test is currently quarantined, derived from its status, the
        collection's quarantine settings and any override.
      example: notQuarantined
    Label:
      type: object
      properties:
        id:
          type: string
          example: 2b3c4d5e-6f70-4a1b-8c9d-0e1f2a3b4c5d
        name:
          type: string
          example: slow-on-prs
        description:
          type: string
          example: Tests that only get slow on pull-request runs.
        color:
          type: string
          description: >-
            The label's hex color, as the web app shows it. A label created by
            `POST /v2/tests/{testId}/add-labels` starts as `#6366F1`.
          example: '#6366F1'
        assignedAt:
          type: string
          format: date-time
          description: >-
            The earliest of `sources[].assignedAt`. Exact when a user applied
            the label; see `MonitorLabelSource.assignedAt` for when a monitor
            did.
          example: '2026-05-01T00:00:00.000Z'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/LabelSource'
          maxItems: 100
          description: >-
            Everything that put this label on the test. More than one entry
            means several sources applied the same label independently. `POST
            /v2/tests/{testId}/remove-labels` removes only the `user` source; a
            `monitor` source stays until the monitor stops applying the label.
      required:
        - id
        - name
        - description
        - color
        - assignedAt
        - sources
      description: >-
        A label on a test, folded across its sources — one entry per label,
        never one per assignment.
    TicketSummary:
      type: object
      properties:
        id:
          type: string
          description: Trunk's id for the linked ticket.
          example: 5d4c3b2a-1f0e-4a1b-8c9d-0e1f2a3b4c5d
        provider:
          $ref: '#/components/schemas/TicketProvider'
        key:
          type: string
          description: >-
            The provider's human-readable key. Mutable on some providers (a Jira
            issue moved between projects gets a new one).
          example: TRUNK-1234
        url:
          type: string
          format: uri
          example: https://acme.atlassian.net/browse/TRUNK-1234
        status:
          type: string
          description: The provider's status name, as last synced.
          example: In Progress
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When Trunk found that the ticketing provider no longer has this
            ticket; null while it exists. A deleted ticket stays linked until it
            is unlinked, and its `status` is the last one synced.
          example: '2026-10-01T09:00:00.000Z'
      required:
        - id
        - provider
        - key
        - url
        - status
        - deletedAt
      description: >-
        The ticket linked to a test, as Trunk last synced it. Reading a test
        never calls the ticketing provider.
    TestMetrics:
      type: object
      properties:
        failureRate:
          type: number
          description: Failing runs over total runs in the period, 0 to 1.
          example: 0.25
        prsImpacted:
          type: integer
          description: >-
            Distinct pull requests that saw this test fail while it was
            unhealthy and not quarantined.
          example: 3
        runCount:
          type: integer
          example: 40
        failureCount:
          type: integer
          example: 10
        durationP95Ms:
          type:
            - integer
            - 'null'
          description: >-
            95th-percentile duration in milliseconds. Null when nothing
            measurable ran in the period — skipped runs are not measured.
          example: 1200
        lastRunAt:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-06-02T10:00:00.000Z'
        lastFailureAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Within the period, unlike the test's own field.
          example: '2026-06-01T10:00:00.000Z'
      required:
        - failureRate
        - prsImpacted
        - runCount
        - failureCount
        - durationP95Ms
        - lastRunAt
        - lastFailureAt
    LabelSource:
      oneOf:
        - $ref: '#/components/schemas/UserLabelSource'
        - $ref: '#/components/schemas/MonitorLabelSource'
      discriminator:
        propertyName: type
        mapping:
          user: '#/components/schemas/UserLabelSource'
          monitor: '#/components/schemas/MonitorLabelSource'
      description: >-
        Something that put a label on a test. A `user` source carries no monitor
        fields and a `monitor` source carries no user.
    TicketProvider:
      type: string
      enum:
        - jiraCloud
        - linear
        - asana
        - jiraDataCenter
      description: The ticketing system a ticket lives in.
      example: jiraCloud
    UserLabelSource:
      type: object
      properties:
        type:
          type: string
          enum:
            - user
        user:
          anyOf:
            - $ref: '#/components/schemas/LabelUser'
            - type: 'null'
          description: >-
            Who applied the label. Null when an API token did, since a token
            resolves to no user, or when that user has since been deleted.
        assignedAt:
          type: string
          format: date-time
          description: When the label was applied.
          example: '2026-06-01T00:00:00.000Z'
      required:
        - type
        - user
        - assignedAt
      description: >-
        A label applied by hand: in the web app, or through `POST
        /v2/tests/{testId}/add-labels`.
    MonitorLabelSource:
      type: object
      properties:
        type:
          type: string
          enum:
            - monitor
        monitorId:
          type: string
          example: 1a2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d
        monitorType:
          $ref: '#/components/schemas/LabelingMonitorType'
        assignedAt:
          type: string
          format: date-time
          description: >-
            The monitor has applied this label since at least this time. Muting
            the monitor, then unmuting it, and editing its label action all
            re-create the assignment, so this can be later than the first time
            it applied the label.
          example: '2026-06-01T00:00:00.000Z'
      required:
        - type
        - monitorId
        - monitorType
        - assignedAt
      description: A label applied by a monitor.
    LabelUser:
      type: object
      properties:
        id:
          type: string
          example: 6f708192-a3b4-4c5d-8e9f-0a1b2c3d4e5f
        name:
          type:
            - string
            - 'null'
          description: >-
            Null only if the user record could not be resolved; the id still
            identifies them.
          example: Ada Lovelace
      required:
        - id
        - name
      description: The person who applied a label.
    LabelingMonitorType:
      type: string
      enum:
        - failureRate
        - passOnRetry
        - failureCount
        - newTest
        - skippedTest
        - slowTest
        - timeoutInflation
      description: A monitor type that can apply a label.
      example: failureRate
  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 new key starts with no
        permissions: it can read merge queues but change nothing in them, and it
        cannot get a Dynamic CI plan. Each endpoint that needs a permission
        names it in its description; the Dynamic CI plan endpoints need
        **Generate Dynamic CI plans**.
    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.

````