> ## 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 detection events

> Lists each verdict a monitor recorded on a test: `active` when it detected the condition it watches for, `inactive` when the test recovered or the monitor was disabled or deleted. An `active` event whose `deactivationReason` is `classifyActionChanged` records a change to the monitor's classify action, not a detection. By default it reads every test collection in your organization; pass `testCollectionId` to narrow to one.

The window is `detectedAfter` to `detectedBefore`, at most 30 days. `detectedBefore` defaults to now and `detectedAfter` to 30 days before it. A wider window is a `400 OUT_OF_RANGE`.

An unknown `monitorId` or `testId` returns an empty page. The 'flag as flaky' mark is not listed here: see a test's status history.



## OpenAPI

````yaml /openapi-v2.json get /v2/detection-events
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 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


    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); impacted-target
    uploads from a GitHub Actions login (10 per second per repository, and
    separately for its fork pull requests); 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/detection-events:
    get:
      tags:
        - detectionEvents
      summary: List detection events
      description: >-
        Lists each verdict a monitor recorded on a test: `active` when it
        detected the condition it watches for, `inactive` when the test
        recovered or the monitor was disabled or deleted. An `active` event
        whose `deactivationReason` is `classifyActionChanged` records a change
        to the monitor's classify action, not a detection. By default it reads
        every test collection in your organization; pass `testCollectionId` to
        narrow to one.


        The window is `detectedAfter` to `detectedBefore`, at most 30 days.
        `detectedBefore` defaults to now and `detectedAfter` to 30 days before
        it. A wider window is a `400 OUT_OF_RANGE`.


        An unknown `monitorId` or `testId` returns an empty page. The 'flag as
        flaky' mark is not listed here: see a test's status history.
      operationId: detectionEvents.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 reads every
              collection in your organization.
            example: aB3xY9kQ
          required: false
          description: >-
            Narrow to one collection, by its id. Omitted reads every collection
            in your organization.
          name: testCollectionId
          in: query
        - schema:
            type: string
            minLength: 1
            description: Only events this monitor recorded.
            example: 1a2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d
          required: false
          description: Only events this monitor recorded.
          name: monitorId
          in: query
        - schema:
            type: string
            minLength: 1
            description: >-
              Comma-separated monitor types to include, e.g.
              `failureRate,passOnRetry`.
            example: failureRate,passOnRetry
          required: false
          description: >-
            Comma-separated monitor types to include, e.g.
            `failureRate,passOnRetry`.
          name: monitorType
          in: query
        - schema:
            type: string
            minLength: 1
            description: Only events on this test, by its globally unique id.
            example: bfeebcf4-0000-8000-8000-000000000001
          required: false
          description: Only events on this test, by its globally unique id.
          name: testId
          in: query
        - schema:
            type: string
            enum:
              - active
              - inactive
            description: Only events with this verdict.
            example: active
          required: false
          description: Only events with this verdict.
          name: monitorStatus
          in: query
        - schema:
            type: boolean
            description: >-
              `true` for only the events that carry a classify action, `false`
              for only those that do not.
            example: true
          required: false
          description: >-
            `true` for only the events that carry a classify action, `false` for
            only those that do not.
          name: isClassificationEvent
          in: query
        - schema:
            type: string
            format: date-time
            description: Only events detected at or after this time.
            example: '2026-06-01T00:00:00.000Z'
          required: false
          description: Only events detected at or after this time.
          name: detectedAfter
          in: query
        - schema:
            type: string
            format: date-time
            description: Only events detected strictly before this time.
            example: '2026-06-30T00:00:00.000Z'
          required: false
          description: Only events detected strictly before this time.
          name: detectedBefore
          in: query
        - schema:
            type: string
            enum:
              - detectedAt
            default: detectedAt
            description: Field to sort by.
          required: false
          description: Field to sort by.
          name: sort
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            description: Sort direction. Newest first by default.
          required: false
          description: Sort direction. Newest first by default.
          name: direction
          in: query
      responses:
        '200':
          description: A page of detection events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectionEventList'
        '400':
          description: '`VALIDATION_FAILED` | `INVALID_CURSOR` | `OUT_OF_RANGE`'
          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.
                OUT_OF_RANGE:
                  summary: OUT_OF_RANGE
                  value:
                    error:
                      code: OUT_OF_RANGE
                      message: >-
                        The requested time window is wider than the endpoint
                        allows
        '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:
    DetectionEventList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DetectionEvent'
          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.
    DetectionEvent:
      type: object
      properties:
        id:
          type: string
          example: 5d6e7f80-91a2-4b3c-8d4e-5f6071829304
        testCollectionId:
          type: string
          description: The id of the test collection the test belongs to.
          example: aB3xY9kQ
        monitorId:
          type: string
          example: 1a2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d
        monitorType:
          $ref: '#/components/schemas/MonitorType'
        monitorStatus:
          $ref: '#/components/schemas/MonitorStatus'
        testId:
          type: string
          description: The test's globally unique id.
          example: bfeebcf4-0000-8000-8000-000000000001
        classification:
          anyOf:
            - $ref: '#/components/schemas/TestStatus'
            - type: 'null'
          description: >-
            The status the event's classify action names. Null when the event
            has no classify action, or when its classify action names a status
            this API does not report; `isClassificationEvent` is still `true`
            then.
        isClassificationEvent:
          type: boolean
          description: >-
            True when the event carries a classify action. It does not mean the
            test's status changed: several monitors can be active on one test,
            and `/tests/{testId}/status-history` records the changes.
          example: true
        deactivationReason:
          anyOf:
            - $ref: '#/components/schemas/DeactivationReason'
            - type: 'null'
          description: >-
            Set when the event comes from a change to the monitor: it was
            disabled or deleted, or its classify action changed. Null for a
            detection, and for a test that recovered.
        detectedAt:
          type: string
          format: date-time
          example: '2026-06-02T10:00:00.000Z'
        monitorKey:
          type:
            - string
            - 'null'
          description: >-
            The detection pipeline's key for the event. Null for an event that a
            change to the monitor caused.
          example: >-
            7a1f0e3d-2b4c-4d5e-8f90-123456789abc:9c8b7a6f-5e4d-4c3b-8a2f-1b2c3d4e5f60:1a2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d:recovered
        sha:
          type:
            - string
            - 'null'
          description: The commit the detection was made on, when it has one.
          example: 9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f
        actions:
          type: array
          items:
            $ref: '#/components/schemas/DetectionEventAction'
          maxItems: 100
          description: >-
            The actions the monitor was configured to take when the event was
            recorded.
        actor:
          anyOf:
            - $ref: '#/components/schemas/DetectionEventActor'
            - type: 'null'
          description: >-
            The person who disabled or deleted the monitor, or changed its
            classify action. Null for an event the detection pipeline made, and
            for a change made with an API token.
      required:
        - id
        - testCollectionId
        - monitorId
        - monitorType
        - monitorStatus
        - testId
        - classification
        - isClassificationEvent
        - deactivationReason
        - detectedAt
        - monitorKey
        - sha
        - actions
        - actor
    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_SCOPE_NOT_FOUND
        - PATHS_FILTER_CONFLICT
        - 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
    MonitorType:
      type: string
      enum:
        - failureRate
        - passOnRetry
        - failureCount
        - newTest
        - skippedTest
        - slowTest
        - timeoutInflation
      description: >-
        A monitor's type. The 'flag as flaky' mark is not a monitor, so `manual`
        is not one of them.
      example: failureRate
    MonitorStatus:
      type: string
      enum:
        - active
        - inactive
      description: >-
        A monitor's verdict on one test: `active` when it detected the condition
        it watches for, `inactive` when the test recovered or the monitor
        stopped watching.
      example: active
    TestStatus:
      type: string
      enum:
        - healthy
        - flaky
        - broken
      description: >-
        A test's current composite status, reconciled across every active
        monitor.
      example: flaky
    DeactivationReason:
      type: string
      enum:
        - monitorDisabled
        - monitorDeleted
        - classifyActionChanged
      description: >-
        Why the event exists because of a change to the monitor itself.
        `monitorDisabled` and `monitorDeleted` are on an `inactive` event: the
        monitor stopped being active on the test. `classifyActionChanged` is on
        an `active` event: someone added, removed or changed the monitor's
        classify action while it was active on the test. That event is not a
        detection.
      example: monitorDisabled
    DetectionEventAction:
      oneOf:
        - $ref: '#/components/schemas/DetectionEventClassifyAction'
        - $ref: '#/components/schemas/DetectionEventLabelAction'
      discriminator:
        propertyName: type
        mapping:
          classify: '#/components/schemas/DetectionEventClassifyAction'
          label: '#/components/schemas/DetectionEventLabelAction'
      description: An action the monitor was configured to take, recorded with the event.
    DetectionEventActor:
      type: object
      properties:
        userId:
          type: string
          example: 6f708192-a3b4-4c5d-8e9f-0a1b2c3d4e5f
        displayName:
          type:
            - string
            - 'null'
          description: Null only if the user record could not be found.
          example: Ada Lovelace
      required:
        - userId
        - displayName
      description: The person whose change to the monitor caused the event.
    DetectionEventClassifyAction:
      type: object
      properties:
        type:
          type: string
          enum:
            - classify
        classification:
          $ref: '#/components/schemas/TestStatus'
      required:
        - type
        - classification
      description: The monitor classified the test.
    DetectionEventLabelAction:
      type: object
      properties:
        type:
          type: string
          enum:
            - label
        labels:
          type: array
          items:
            $ref: '#/components/schemas/DetectionEventLabel'
          maxItems: 100
      required:
        - type
        - labels
      description: The monitor applied labels to the test, or removed them.
    DetectionEventLabel:
      type: object
      properties:
        name:
          type: string
          example: slow
        color:
          type: string
          example: '#f97316'
      required:
        - name
        - color
      description: A label as it was when the event was recorded.
  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 impacted targets**
        (`PUT /v2/impacted-targets`), for the repository the run belongs to;
        every other endpoint refuses it.

````