Test Insights

Access data from Test Insights.

Search tests #

GET /ci/{owner}/repositories/{repository}/search/tests

Search tests in a repository.

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Query Parameters
test_name string[]

Filter by test name. Pass multiple times to combine matches. Supports glob patterns (`*`, `?`). Omit to return all test identities.

sort "executions_count" | "test_name" | "pipeline_name" | "job_name" | "health_status" | "health_confidence" | "failed_executions_impact" | "failed_executions_ratio"

Sort field

direction "asc" | "desc"

Sort direction

test_name_exclude string[]

The test name to exclude

pipeline_name string[]

The pipeline name to filter on

pipeline_name_exclude string[]

The pipeline name to exclude

job_name string[]

The job name to filter on

job_name_exclude string[]

The job name to exclude

health_status ("healthy" | "flaky" | "broken")[]

The health status to filter on

health_status_exclude ("healthy" | "flaky" | "broken")[]

The health status to exclude

health_confidence ("low" | "medium" | "high")[]

The health confidence to filter on

health_confidence_exclude ("low" | "medium" | "high")[]

The health confidence to exclude

failed_executions_impact ("low" | "medium" | "high")[]

The failed executions impact to filter on

failed_executions_impact_exclude ("low" | "medium" | "high")[]

The failed executions impact to exclude

cursor string

The opaque cursor of the current page. Must be extracted from RFC 5988 pagination links to get first/previous/next/last pages

per_page integer

The number of items per page

min: 1 · max: 100

Responses
200 Successful Response
sizeintegerrequired

The number of items in this page

per_pageintegerrequired

The number of items per page

testsTestSearchResult[]required

Test identities matching the search query.

test_idstring <uuid5>required

Stable identifier of the test. Pass it to the per-test endpoints to fetch details, metrics, or failures.

test_namestringrequired

Fully qualified name of the test as reported by the CI provider.

pipeline_namestringrequired

Name of the pipeline (workflow) that ran the test.

job_namestringrequired

Name of the job within the pipeline that ran the test.

metricsTestSearchResultMetricsrequired

Health metrics of the test identity.

health_status"healthy" | "flaky" | "broken"required

Current health classification of the test: healthy, flaky, or broken.

Enum: healthy flaky broken
health_confidence"low" | "medium" | "high"required

Confidence in the health classification, derived from how many times the test has been rerun.

Enum: low medium high
failed_executions_impact"low" | "medium" | "high" | nullrequired

Impact of the test's failures, derived from its failure ratio. `null` for healthy tests, which have no meaningful failure impact.

totalintegerrequired

Total number of test identities matching the search query, across all pages.

Example Response 
                          {
  "size": 0,
  "per_page": 0,
  "tests": [
    {
      "test_id": "string",
      "test_name": "string",
      "pipeline_name": "string",
      "job_name": "string",
      "metrics": {}
    }
  ],
  "total": 0
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/search/tests" \
  -H "Authorization: Bearer <token>"

Get detailed information about a test #

GET /ci/{owner}/repositories/{repository}/tests/{test_id}

Get detailed information about a test.

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
test_id string <uuid5> required

ID of the test

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
repositorystringrequired
test_namestringrequired
test_idstring <uuid5>required
health_statusstringrequired
last_conclusionstringrequired
failure_rationumberrequired
flakiness_rationumberrequired
success_rationumberrequired
flaky_detection_enabledbooleanrequired
first_failure_atstring <date-time> | nullrequired
first_failure_commitstring | nullrequired
first_failure_pullGetTestDetailsResponsePull | nullrequired
idintegerrequired
numberintegerrequired
titlestringrequired
userGetTestDetailsResponseUserrequired
idintegerrequired
loginstringrequired
last_failure_atstring <date-time> | nullrequired
last_success_atstring <date-time> | nullrequired
test_frameworkstring | nullrequired
test_framework_versionstring | nullrequired
test_programming_languagestring | nullrequired
test_filepathstring | nullrequired
test_function_namestring | nullrequired
Example Response 
                          {
  "repository": "string",
  "test_name": "string",
  "test_id": "string",
  "health_status": "string",
  "last_conclusion": "string",
  "failure_ratio": 0,
  "flakiness_ratio": 0,
  "success_ratio": 0,
  "flaky_detection_enabled": true,
  "first_failure_at": "2024-01-15T09:00:00Z",
  "first_failure_commit": "string",
  "first_failure_pull": {
    "id": 0,
    "number": 0,
    "title": "string",
    "user": {
      "id": 0,
      "login": "string"
    }
  },
  "last_failure_at": "2024-01-15T09:00:00Z",
  "last_success_at": "2024-01-15T09:00:00Z",
  "test_framework": "string",
  "test_framework_version": "string",
  "test_programming_language": "string",
  "test_filepath": "string",
  "test_function_name": "string"
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/tests/:test_id" \
  -H "Authorization: Bearer <token>"

Get a single test stat as a time series #

GET /ci/{owner}/repositories/{repository}/tests/{test_id}/stats/{stat}

Return one of the test stats bucketed over the requested time range, with a summary value over the full window. Binning adapts to the requested window (1h, 4h, 1d, 2d).

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
test_id string <uuid5> required

ID of the test

stat "success_count" | "failure_count" | "flaky_count" | "mean_duration" required
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Query Parameters
start string <date-time>

Start of the time range. Defaults to `end - 1 day` when omitted.

end string <date-time>

End of the time range. Defaults to `start + 1 day` when only start is provided, or `now` otherwise.

Responses
200 Successful Response
Discriminated by stat — 4 types
success_countTestCountStatsResponse
valueintegerrequired
value_over_time_TestStatsBucket_int_[]required
startstring <date-time>required
endstring <date-time>required
valueintegerrequired
stat"success_count" | "failure_count" | "flaky_count"required
Enum: success_count failure_count flaky_count
failure_countTestCountStatsResponse
valueintegerrequired
value_over_time_TestStatsBucket_int_[]required
startstring <date-time>required
endstring <date-time>required
valueintegerrequired
stat"success_count" | "failure_count" | "flaky_count"required
Enum: success_count failure_count flaky_count
flaky_countTestCountStatsResponse
valueintegerrequired
value_over_time_TestStatsBucket_int_[]required
startstring <date-time>required
endstring <date-time>required
valueintegerrequired
stat"success_count" | "failure_count" | "flaky_count"required
Enum: success_count failure_count flaky_count
mean_durationTestDurationStatsResponse
valuenumberrequired
value_over_time_TestStatsBucket_float_[]required
startstring <date-time>required
endstring <date-time>required
valuenumberrequired
statstringrequired
Example Response 
                          {
  "value": 0,
  "value_over_time": [
    {
      "start": "2024-01-15T09:00:00Z",
      "end": "2024-01-15T09:00:00Z",
      "value": 0
    }
  ],
  "stat": "success_count"
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/tests/:test_id/stats/:stat" \
  -H "Authorization: Bearer <token>"

Get a test's health transitions over time #

GET /ci/{owner}/repositories/{repository}/tests/{test_id}/health-transitions

Return the moments a test's health (healthy/flaky/broken) changed over the requested window — the edges of the per-bucket classification, not the full series. Health is derived per time bucket (binning adapts to the window), so a transition is timestamped to a bucket boundary, not an individual run.

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
test_id string <uuid5> required

ID of the test

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Query Parameters
start string <date-time>

Start of the time range. Defaults to `end - 1 day` when omitted.

end string <date-time>

End of the time range. Defaults to `start + 1 day` when only start is provided, or `now` otherwise.

Responses
200 Successful Response
transitionsHealthTransition[]required

Health changes over the window, oldest first. Consecutive entries always differ; the first entry is the earliest classification observed in the window. Health is classified per time bucket (binning adapts to the window: 1h, 4h, 1d, 2d), so timestamps land on bucket boundaries, not individual runs.

atstring <date-time>required

Bucket boundary at which the test's health changed to `health_status`.

health_status"healthy" | "flaky" | "broken"required

Health the test held from `at` until the next transition.

Enum: healthy flaky broken
exception_typestring | null

Exception raised by the first failing run of the episode this transition opens. Always null for a recovery, and when no failing run is retained.

pull_requestGetTestDetailsResponsePull | null

Pull request whose merge commit introduced the first failing run of the episode this transition opens. Null for a recovery — a test can stop failing without a PR fixing it, so no 'fixed by' is attributed — and whenever the failing commit cannot be traced back to a merged pull request.

idintegerrequired
numberintegerrequired
titlestringrequired
userGetTestDetailsResponseUserrequired
idintegerrequired
loginstringrequired
first_activity_atstring <date-time> | nullrequired

Start of the earliest bucket with any executions in the window, or null when the test had no activity. A consumer can treat a `first_activity_at` well after the window start as the test's genuine origin, and one at the window edge as history that predates the retained window.

Example Response 
                          {
  "transitions": [
    {
      "at": "2024-01-15T09:00:00Z",
      "health_status": "healthy",
      "exception_type": "string",
      "pull_request": {}
    }
  ],
  "first_activity_at": "2024-01-15T09:00:00Z"
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/tests/:test_id/health-transitions" \
  -H "Authorization: Bearer <token>"

Get test failures #

GET /ci/{owner}/repositories/{repository}/tests/{test_id}/failures

Get test failures.

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
test_id string <uuid5> required

ID of the test

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
failuresTestFailure[]required
idstring <uuid5>required
exception_typestringrequired
exception_messagestringrequired
failure_countintegerrequired
first_failure_atstring <date-time>required
last_failure_atstring <date-time>required
Example Response 
                          {
  "failures": [
    {
      "id": "string",
      "exception_type": "string",
      "exception_message": "string",
      "failure_count": 0,
      "first_failure_at": "2024-01-15T09:00:00Z",
      "last_failure_at": "2024-01-15T09:00:00Z"
    }
  ]
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/tests/:test_id/failures" \
  -H "Authorization: Bearer <token>"

Get test failure #

GET /ci/{owner}/repositories/{repository}/tests/{test_id}/failures/{failure_id}

Get test failure.

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
test_id string <uuid5> required

ID of the test

failure_id string <uuid5> required

ID of the failure

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
idstring <uuid5>required
exception_typestringrequired
exception_messagestringrequired
failure_countintegerrequired
first_failure_atstring <date-time>required
last_failure_atstring <date-time>required
latest_eventsTestFailureEvent[]required
idstringrequired
failed_atstring <date-time>required
exception_stacktracestring | nullrequired
test_filepathstring | nullrequired
test_programming_languagestring | nullrequired
job_urlstring | null
Example Response 
                          {
  "id": "string",
  "exception_type": "string",
  "exception_message": "string",
  "failure_count": 0,
  "first_failure_at": "2024-01-15T09:00:00Z",
  "last_failure_at": "2024-01-15T09:00:00Z",
  "latest_events": [
    {
      "id": "string",
      "failed_at": "2024-01-15T09:00:00Z",
      "exception_stacktrace": "string",
      "test_filepath": "string",
      "test_programming_language": "string",
      "job_url": "string"
    }
  ]
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/tests/:test_id/failures/:failure_id" \
  -H "Authorization: Bearer <token>"

List a test's executions #

GET /ci/{owner}/repositories/{repository}/tests/{test_id}/executions

List the identities under which this test ran on the default branch over the requested time window, ordered by total executions.

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
test_id string <uuid5> required

ID of the test

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Query Parameters
sort "executions_count" | "pipeline_name" | "job_name"

Sort field

direction "asc" | "desc"

Sort direction

cursor string

The opaque cursor of the current page. Must be extracted from RFC 5988 pagination links to get first/previous/next/last pages

per_page integer

The number of items per page

min: 1 · max: 100

start string <date-time>

Start of the time range. Defaults to `end - 1 day` when omitted.

end string <date-time>

End of the time range. Defaults to `start + 1 day` when only start is provided, or `now` otherwise.

Responses
200 Successful Response
sizeintegerrequired

The number of items in this page

per_pageintegerrequired

The number of items per page

executionsTestExecutionResult[]required

Test identities under which this test ran on the default branch over the requested time window, ordered by total executions.

test_idstring <uuid5>required

Stable identifier of the test. Matches the `test_id` in the URL.

test_namestringrequired

Fully qualified name of the test as reported by the CI provider.

pipeline_namestringrequired

Name of the pipeline (workflow) that ran the test.

job_namestringrequired

Name of the job within the pipeline that ran the test.

executions_countintegerrequired

Number of executions of this test under this identity over the requested time window.

Example Response 
                          {
  "size": 0,
  "per_page": 0,
  "executions": [
    {
      "test_id": "string",
      "test_name": "string",
      "pipeline_name": "string",
      "job_name": "string",
      "executions_count": 0
    }
  ]
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/tests/:test_id/executions" \
  -H "Authorization: Bearer <token>"

List quarantined tests #

GET /ci/{owner}/repositories/{repository}/quarantines

List the tests currently quarantined in the repository, ordered by quarantine creation time ascending. A quarantine applies to a specific branch or to all branches when `branch` is `null`. Pagination is opt-in: pass `per_page` (and optionally `cursor`) to receive a bounded page with RFC 5988 navigation links. Omitting `per_page` returns the full list in a single response — this shortcut exists for backward compatibility and is expected to go away once all callers paginate.

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Query Parameters
branch string

min length: 1 · max length: 255

test_id string <uuid>
source "manual" | "auto"
cursor string

The opaque cursor of the current page. Must be extracted from RFC 5988 pagination links to get first/previous/next/last pages.

per_page integer

The number of items per page. Omit to receive the full list in a single response; pass a value to opt into RFC 5988 cursor pagination.

min: 1 · max: 100

Responses
200 Successful Response
sizeintegerrequired

The number of items in this page

per_pageinteger | nullrequired

The number of items per page, or `null` when the endpoint was called without `per_page` and returned the full list in a single response.

quarantined_testsQuarantinedTest[]required
idstring <uuid>required

Unique identifier of the quarantine record.

test_namestringrequired

Fully qualified name of the quarantined test.

test_idstring <uuid>required

Stable identifier of the test, derived from its name. Identical across every quarantine of the same test and matches the `test_id` filter on the list endpoint.

reasonstringrequired

Free-form reason recorded when the test was quarantined.

branchstring | nullrequired

Branch name this quarantine applies to. `null` means the test is quarantined on every branch.

created_atstring <date-time>required

UTC timestamp when the test was added to quarantine.

source"manual" | "auto"

How the test got quarantined: `manual` (user action) or `auto` (auto-quarantined).

Enum: manual auto
is_recoveredbooleanrequired

True when recent runs of this test are healthy, suggesting the quarantine could be removed.

Example Response 
                          {
  "size": 0,
  "per_page": 0,
  "quarantined_tests": [
    {
      "id": "string",
      "test_name": "string",
      "test_id": "string",
      "reason": "string",
      "branch": "string",
      "created_at": "2024-01-15T09:00:00Z",
      "source": "manual",
      "is_recovered": true
    }
  ]
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/quarantines" \
  -H "Authorization: Bearer <token>"

Mark a test as quarantined #

POST /ci/{owner}/repositories/{repository}/quarantines

Add a test to the CI Quarantine for a repository

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Request Body
test_namestringrequired

The fully qualified name of the test that needs to be quarantined

max length: 10000
reasonstringrequired

Reason for the test being added to the quarantine

max length: 10000
branchstring | null

Branch name on which the test should be quarantined. If not specified, it will be quarantined on all branches.

Responses
201 Successful Response
idstring <uuid>required

The ID of the created quarantine

Example Response 
                          {
  "id": "string"
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X POST "https://api.mergify.com/v1/ci/:owner/repositories/:repository/quarantines" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "test_name": "string",
  "reason": "string",
  "branch": "string"
}'

Get a quarantined test #

GET /ci/{owner}/repositories/{repository}/quarantines/{quarantine_id}

Retrieve a single quarantined test by its quarantine ID.

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
quarantine_id string <uuid> required
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
idstring <uuid>required

Unique identifier of the quarantine record.

test_namestringrequired

Fully qualified name of the quarantined test.

test_idstring <uuid>required

Stable identifier of the test, derived from its name. Identical across every quarantine of the same test and matches the `test_id` filter on the list endpoint.

reasonstringrequired

Free-form reason recorded when the test was quarantined.

branchstring | nullrequired

Branch name this quarantine applies to. `null` means the test is quarantined on every branch.

created_atstring <date-time>required

UTC timestamp when the test was added to quarantine.

source"manual" | "auto"

How the test got quarantined: `manual` (user action) or `auto` (auto-quarantined).

Enum: manual auto
is_recoveredbooleanrequired

True when recent runs of this test are healthy, suggesting the quarantine could be removed.

Example Response 
                          {
  "id": "string",
  "test_name": "string",
  "test_id": "string",
  "reason": "string",
  "branch": "string",
  "created_at": "2024-01-15T09:00:00Z",
  "source": "manual",
  "is_recovered": true
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/quarantines/:quarantine_id" \
  -H "Authorization: Bearer <token>"

Remove a quarantine #

DELETE /ci/{owner}/repositories/{repository}/quarantines/{quarantine_id}

Remove a quarantine with its id

Authorization (any one of)
Admin Application Key CI Application Key GitHub Token
Path Parameters
quarantine_id string <uuid> required
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
any
204 No content
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X DELETE "https://api.mergify.com/v1/ci/:owner/repositories/:repository/quarantines/:quarantine_id" \
  -H "Authorization: Bearer <token>"

Get a single test stat as a time series #

GET /ci/{owner}/repositories/{repository}/tests/stats/{stat}

Return one test stat with a window summary `value` and a per-day `value_over_time` series of failed executions.

Authorization (any one of)
Admin Application Key GitHub Token
Path Parameters
stat "total_tests" | "healthy_tests" | "broken_tests" | "flaky_tests" | "failed_executions" required
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Query Parameters
test_name string[]

The test name to filter on

test_name_exclude string[]

The test name to exclude

job_name string[]

The job name to filter on

job_name_exclude string[]

The job name to exclude

pipeline_name string[]

The pipeline name to filter on

pipeline_name_exclude string[]

The pipeline name to exclude

health_confidence ("low" | "medium" | "high")[]

The health confidence to filter on

health_confidence_exclude ("low" | "medium" | "high")[]

The health confidence to exclude

failed_executions_impact ("low" | "medium" | "high")[]

The failed executions impact to filter on

failed_executions_impact_exclude ("low" | "medium" | "high")[]

The failed executions impact to exclude

Responses
200 Successful Response
stat"total_tests" | "healthy_tests" | "broken_tests" | "flaky_tests" | "failed_executions"required
Enum: total_tests healthy_tests broken_tests flaky_tests failed_executions
valueintegerrequired
value_over_timeTestStatBucket[]required
startstring <date-time>required
endstring <date-time>required
valueintegerrequired
Example Response 
                          {
  "stat": "total_tests",
  "value": 0,
  "value_over_time": [
    {
      "start": "2024-01-15T09:00:00Z",
      "end": "2024-01-15T09:00:00Z",
      "value": 0
    }
  ]
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/ci/:owner/repositories/:repository/tests/stats/:stat" \
  -H "Authorization: Bearer <token>"

Was this page helpful?