> ## 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.

# Fix Flaky Tests

> Give a coding agent the context it needs to fix a flaky test, from Trunk's API.

A coding agent such as Cursor or Claude Code can fix a flaky test when it has the right context: which test, when it became flaky, and how it fails. Trunk's [API](https://docs.trunk.io/api.md) provides all of it. Have your agent follow these steps.

## Before you begin

* Create an [API key](https://docs.trunk.io/api/authentication#api-keys) for the agent. Reading tests needs no permissions. To have it link or create tickets, give it the **Create tickets** permission.
* Turn on **CI Intelligence** for the repository, at **Settings** → **Repositories**, with the [Trunk CI GitHub App](https://docs.trunk.io/setup/integrations/github/trunk-ci.md) installed. It provides the failure output in step 2, and keeps logs for 30 days. Without it, have the agent open the run's `buildUrl` instead.

## 1. Find the tests to fix

Start the agent in one of two ways:

* **From a webhook.** Subscribe the agent's endpoint to the [`v2.test_case.status_changed`](../webhooks/index) event and act when `new_status` is `FLAKY`. Pass `test_case.id` to the calls below.
* **On a schedule.** Call [`GET /v2/tests`](https://docs.trunk.io/api/tests/list-and-search-tests) with `status=flaky`, `newlyFlaky=true` and a `period`, narrowed with `testCollectionId` or `owner` if you like.

## 2. Gather context

| What the agent needs | Call |
| - | - |
| The test's name, file, owners, active monitors and failure rate | [`GET /v2/tests/{testId}`](https://docs.trunk.io/api/tests/get-a-test) with `include=metrics&period=7d` |
| When the test became flaky, and which monitor flagged it | [`GET /v2/tests/{testId}/status-history`](https://docs.trunk.io/api/tests/list-a-tests-status-transitions) |
| Failing runs, with branch, commit, pull request, CI job and build URL | [`GET /v2/tests/{testId}/test-runs`](https://docs.trunk.io/api/tests/list-a-tests-runs) with `conclusion=failure` |
| The failure output | `GET /v2/ci-jobs` with the test's `repositoryId` and the run's `sha` as `commitSha`. Pick the job whose `name` matches the run's `jobName`; its `failure.logExcerpt` gives the failing lines. Read more of the log with `GET /v2/ci-jobs/{id}/log-lines`. |

## 3. Fix and track

* Have the agent open a pull request that fixes the root cause, not one that raises a timeout or loosens an assertion.
* To track the work, link the pull request's ticket with [`POST /v2/tests/{testId}/ticket`](https://docs.trunk.io/api/tests/link-a-ticket-to-a-test), or create one with [`POST /v2/tests/{testId}/create-ticket`](https://docs.trunk.io/api/tests/create-a-ticket-for-a-test).

Keep monitoring the test afterwards to confirm the fix worked.

## Related

* [Route Flaky Tests to Their Owners](https://docs.trunk.io/flaky-tests/recipes/route-flaky-tests-to-owners.md). File the ticket and tell the owning team, before the agent picks the test up.
* [Tighten Test Timeouts](https://docs.trunk.io/flaky-tests/recipes/tighten-test-timeouts.md). Have the agent fix tests that wait out their timeouts.
* [Autofix CI Failures](https://docs.trunk.io/flaky-tests/recipes/autofix-ci-failures.md). Fix a red CI run as soon as it fails, with Trunk's MCP server.
