---
title: "List test states"
method: GET
path: "/ci/{owner}/repositories/{repository}/test-states"
tags: ["test_insights"]
---

# List test states

`GET /ci/{owner}/repositories/{repository}/test-states`

## Request

- Base URL: `https://api.mergify.com/v1`
- URL: `https://api.mergify.com/v1/ci/{owner}/repositories/{repository}/test-states`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

List the states the repository's tests are put in, ordered by `sort` and `direction` (creation time ascending by default). A state applies to the branch, pipeline and job it names, or to every one of them when `null`.

## Path parameters

- `repository` string, required: The name of the repository
- `owner` string, required: The owner of the repository

## Query parameters

- `state` TestStateValue[], nullable: The states to filter on.
- `test_id` string[], nullable: The test identifier to filter on
- `source` QuarantineSource[], nullable: The sources to filter on.
- `branch_name` string[], nullable: The branch name to filter on. Test states applying to every branch always match.
- `branch_name_exclude` string[], nullable: The branch name to exclude. Test states applying to every branch are kept.
- `pipeline_name` string[], nullable: The pipeline name to filter on. Test states applying to every pipeline always match.
- `pipeline_name_exclude` string[], nullable: The pipeline name to exclude. Test states applying to every pipeline are kept.
- `job_name` string[], nullable: The job name to filter on. Test states applying to every job always match.
- `job_name_exclude` string[], nullable: The job name to exclude. Test states applying to every job are kept.
- `test_name` string[], nullable: The test name to filter on
- `test_name_exclude` string[], nullable: The test name to exclude
- `health_status` HealthStatus[], nullable: The health status to filter on. Tests with no recent runs are left out.
- `health_status_exclude` HealthStatus[], nullable: The health status to exclude. Tests with no recent runs are kept.
- `cursor` string, nullable: The opaque cursor of the current page. Must be extracted from RFC 5988 pagination links to get the previous/next pages
- `per_page` integer: The number of items per page
- `sort` 'created_at' | 'test_name' | 'pipeline_name' | 'job_name' | 'health_status' | 'source'
- `direction` 'asc' | 'desc': Sort direction

## Response `200`

Successful Response

- TestStatesResponse
  - `size` integer, required: The number of items in this page
  - `per_page` integer, required: The number of items per page
  - `test_states` TestState[], required
    - `id` string, uuid, required: Unique identifier of the test state.
    - `test_name` string, required: Fully qualified name of the test.
    - `test_id` string, uuid, required: Stable identifier of the test, derived from its name. Identical across every state of the same test and matches the `test_id` filter on the list endpoint.
    - `state` 'quarantined', required
    - `reason` string, required: Free-form reason recorded when the test was put in this state.
    - `issue_url` string, nullable, required: Link to where the fix of the test is tracked, such as an issue. `null` when none was given.
    - `branch_name` string, nullable, required: Branch this state applies to. `null` means every branch.
    - `pipeline_name` string, nullable, required: Pipeline this state applies to. `null` means every pipeline.
    - `job_name` string, nullable, required: Job this state applies to. `null` means every job.
    - `created_at` string, date-time, required: UTC timestamp when the test was put in this state.
    - `source` 'manual' | 'auto', required
    - `health_status` 'healthy' | 'flaky' | 'broken', required
    - `is_recovered` boolean, required: True when recent runs of this test are healthy.
    - `unquarantine_when_healthy` boolean, required: For the `quarantined` state: true when Mergify unquarantines the test once it recovers.
  - `total` integer, required: Total number of test states matching the filters, across all pages.

## Other responses

- `403`: Forbidden
- `404`: Not found
- `409`: Conflict
- `422`: Unprocessable entity

## Changes

- **2026-10-22** `f0fe01773ba8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mergify/apis/mergify-api/changes/ci/:owner/repositories/:repository/test-states/get.md)

---

[API](https://skmtc.dev/mergify/apis/mergify-api.md) · [All operations](https://skmtc.dev/mergify/apis/mergify-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mergify/apis/mergify-api/revisions/00b8f4a31190?raw)