> ## Documentation Index
> Fetch the complete documentation index at: https://trunk-4cab4936-sam-gutentag-api-conventions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Flaky Tests API

> REST API for checking Trunk service status and fetching unhealthy or quarantined tests in your project.

The Trunk Flaky Tests API provides access to check the status of Trunk services and fetch [unhealthy](../detection/) or [quarantined](../quarantining/) tests in your project. The API is an HTTP REST API, returns JSON from all requests, and uses standard HTTP response codes.

All requests must be [authenticated](../../setup-and-administration/apis/#authentication) by providing the `x-api-token` header.

### API conventions

Behavior that applies across endpoints — pagination, rate limits, webhook-to-API state propagation, and a few support-only fields.

#### Pagination with `page_token`

List endpoints (`list-unhealthy-tests`, `list-quarantined-tests`, `list-failing-tests`) return at most `page_size` results per call, capped at 100. To page through results, use the `next_page_token` returned in the response as the `page_token` on the next request.

For the **first page**, omit `page_token` or pass an empty string. Passing a value that didn't come from a prior response returns a 500.

```bash theme={null}
# First call — no page_token
curl -X POST https://api.trunk.io/v1/flaky-tests/list-unhealthy-tests \
  -H "x-api-token: $TRUNK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_url_slug": "your-org",
    "repo": { "host": "github.com", "owner": "your-org", "name": "your-repo" },
    "page_query": { "page_size": 50 }
  }'

# Subsequent call — pass next_page_token from the previous response
curl -X POST https://api.trunk.io/v1/flaky-tests/list-unhealthy-tests \
  -H "x-api-token: $TRUNK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_url_slug": "your-org",
    "repo": { "host": "github.com", "owner": "your-org", "name": "your-repo" },
    "page_query": { "page_size": 50, "page_token": "<next_page_token from prior response>" }
  }'
```

<Info>
  If the web app shows a test as flaky but `list-unhealthy-tests` doesn't return it on the first page, keep paginating — large result sets span multiple pages, and the test you're looking for may not appear until later pages.
</Info>

The response also includes `prev_page_token` and `last_page_token` for walking the result set in either direction.

#### Rate limits

There is no externally published rate-limit SLO on the org API token, but the practical ceiling is high enough for reasonable polling and dashboard use.

If you're building automation that polls a list endpoint on a tight interval — for example, a "is this PR in the queue?" check that runs on every push — share the expected request rate with [Trunk support](mailto:support@trunk.io) before rolling it out so we can confirm it's within range.

#### Webhook-to-API state propagation

When a [`status_changed` webhook](../../webhooks/) fires for a test (for example, transitioning from `healthy` to `flaky`), the new status is reflected immediately in subsequent `list-unhealthy-tests` and `list-quarantined-tests` responses. There is no eventual-consistency window between the webhook and the read APIs — if you act on a webhook and then call the API, you'll see the post-event state.

#### Bundle Upload ID

The `trunk-analytics-cli upload` command prints a `Bundle Upload ID` after each upload. This ID is intended for support handoff, not for direct lookup:

* It is not URL-searchable in the web app.
* It is not exposed via the public API today.

If you need to map a specific upload to its run in the web app, share the ID with [Trunk support](mailto:support@trunk.io).

#### Auto-analysis (Beta) rate limit

Auto-analysis runs (the [autofix flaky tests](../../agents/autofix-flaky-tests) and [autofix CI failures](../../agents/autofix-ci-failures) agents) have a default monthly cap while the feature is in Beta. If you're hitting the cap, contact [Trunk support](mailto:support@trunk.io) to request a higher limit for your org.

#### GraphQL is private

The Trunk web app uses a private GraphQL endpoint internally. It is not a public interface, has no compatibility guarantee, and may change without notice. Build against the documented REST endpoints below.

***

### Endpoint reference

<Columns cols={2}>
  <Card title="Get the details of a test case" href="/flaky-tests/reference/api-reference/get-the-details-of-a-test-case" />

  <Card title="Link a ticket to a test case" href="/flaky-tests/reference/api-reference/link-a-ticket-to-a-test-case" />

  <Card title="Get a list of distinct tests that failed in the given time range" href="/flaky-tests/reference/api-reference/get-a-list-of-distinct-tests-that-failed-in-the-given-time-range" />

  <Card title="Get a list of unhealthy tests" href="/flaky-tests/reference/api-reference/get-a-list-of-unhealthy-tests" />

  <Card title="Get a list of quarantined tests" href="/flaky-tests/reference/api-reference/get-a-list-of-quarantined-tests" />
</Columns>