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 or quarantined 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 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.

# 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>" }
  }'

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.

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 before rolling it out so we can confirm it’s within range.

Webhook-to-API state propagation

When a status_changed webhook 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.

Auto-analysis (Beta) rate limit

Auto-analysis runs (the autofix flaky tests and autofix CI failures agents) have a default monthly cap while the feature is in Beta. If you’re hitting the cap, contact Trunk support 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

Get the details of a test case

Link a ticket to a test case

Get a list of distinct tests that failed in the given time range

Get a list of unhealthy tests

Get a list of quarantined tests