Document flaky-tests API conventions and pagination

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": "<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"
@@ -33,4 +102,4 @@ All requests must be [authenticated](../../setup-and-administration/apis/#authen
     href="/flaky-tests/reference/api-reference/get-a-list-of-quarantined-tests"
   />
 
-</Columns>
+</Columns>