From 4aaa9a76402f6866899973cbd7c685844b1e0854 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Wed, 20 May 2026 16:47:07 -0700 Subject: [PATCH] add API conventions: rate limits, page_token pagination, state propagation, Bundle Upload ID Expand the Flaky Tests API reference index page with an "API conventions" section covering behavior that applies across endpoints. Sourced from recurring customer questions: page_token misuse returning 500s, "missing" tests that were actually on later pages, rate-limit expectations for polling automation, and webhook-to-API immediacy. Also documents three things that weren't surfaced anywhere in narrative form: Bundle Upload IDs are support-only, auto-analysis has a default monthly cap during Beta, and the UI's GraphQL endpoint is private. Co-Authored-By: Claude Opus 4.7 (1M context) --- flaky-tests/reference/api-reference.mdx | 71 ++++++++++++++++++++++++- 1 file changed, 70 insertions(+), 1 deletion(-) diff --git a/flaky-tests/reference/api-reference.mdx b/flaky-tests/reference/api-reference.mdx index d7dee9a0..c02cedd3 100644 --- a/flaky-tests/reference/api-reference.mdx +++ b/flaky-tests/reference/api-reference.mdx @@ -7,6 +7,75 @@ The Trunk Flaky Tests API provides access to check the status of Trunk services 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 +# 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": "" } + }' +``` + + +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](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 + - \ No newline at end of file +