If you are just getting started with Tesults and have not submitted test results data to Tesults yet and cannot see any results data in the results view, read the integration documentation instead. Once that has been completed, you can use the Tesults API to retrieve results data to make decisions within your continuous integration and deployment pipelines.
Insights
Insights apply the target's current result interpretation rules, including supported Playwright expected-status handling. Build records are excluded from test-case analysis. AI explanations suggest possible causes; check the underlying results before acting.
Each endpoint has its own history scope, described below. An empty finding list is not proof that a target has no problems outside that scope. Missing or unreadable evidence returns an error rather than a successful empty analysis. For conversational questions within Tesults, see Ask about these results; for an external agent, see MCP setup.
The Insights API exposes the same cross-run intelligence available in the Tesults UI, making it accessible to external tools, AI agents, and CI/CD integrations. All responses are structured for direct use in automated pipelines or as input to an LLM without further preprocessing.
Explain runFlaky tests
Regressions
What changed
Explain case
Explain run
Returns a structured explanation of a specific test run: a plain-language summary, possible causes, the number of non-passing tests, and the key failure patterns observed. The root_cause field contains an AI hypothesis, not a verified diagnosis.
Analysis covers at most 100 non-passing tests, including unknown results. When this limit is exceeded, truncated is true and analyzed_count gives the number included; failed_count remains the total non-passing count. Failure entries include a test hash when available so clients can retrieve the underlying evidence.
This is useful for surfacing actionable insight in CI/CD pipelines, Slack notifications, or as context for an AI agent investigating a broken build. The response mirrors what the Tesults UI displays after a run completes.
curl https://www.tesults.com/api/insights/explain-run
?target=target_id
&run=run_id
-H "Authorization: Bearer token"
Endpoint
Headers
The Authorization header is required for all requests to the Tesults API. See the authentication documentation for details.
Authorization
Bearer <token>
Parameters
| Name | Value |
|---|---|
| target | The target id for the target that contains the run to explain. Retrieve target ids from the Targets API. |
| run | The run id of the test run to explain. Use the created_time value returned by the Results API as the run id, or retrieve it from the Tesults UI. |
Response
Successful response:
{
"data": {
"code": 200,
"message": "Success",
"insight": {
"summary": "149 of 150 tests passed. 1 test failed in the Checkout suite.",
"failed_count": 1,
"failure_patterns": [
{
"label": "Checkout timeout",
"root_cause": "Possible payment gateway timeout; investigate the service logs.",
"common_pattern": "Timeout during order submission",
"confidence": "medium",
"failed_count": 1,
"failures": [{"name": "Submit order", "hash": "example-case-hash", "suite": "Checkout", "reason": "Request timed out"}]
}
]
}
}
}Failure response:
{
"error": {
"code": 400,
"message": "Missing parameter: target"
}
}Successful responses return JSON containing a data property. Error responses return JSON containing an error property. Both data and error values contain a code and message property, specifying the http status code and a message containing additional context.
Successful responses contain an insight object with a summary, failed_count and a failure_patterns array. Each pattern includes label, root_cause, common_pattern, confidence (high, medium or low), failed_count and the associated failures.
Flaky tests
Returns the list of tests identified as flaky for a given target, along with each test's failure rate, the timestamp of its last failure, and a simple classification such as "likely flaky".
Tests are flagged when their interpreted result changes more than twice across up to 10 recent runs in the requested range. Changes between pass, fail and unknown count, including pass/unknown changes. A consistently failing test is not flagged as flaky. Use the optional from and to parameters to constrain the time window.
The failure_rate counts fail results divided by appearances in the analysed runs, not unknown results. A pass/unknown pattern can therefore have a zero failure rate and no last_failure or last_failure_iso. Tests are matched across runs by hash, which is included in each finding.
curl https://www.tesults.com/api/insights/flaky-tests
?target=target_id
-H "Authorization: Bearer token"
curl https://www.tesults.com/api/insights/flaky-tests
?target=target_id
&from=1700000000000
&to=1700086400000
-H "Authorization: Bearer token"
Endpoint
Headers
The Authorization header is required for all requests to the Tesults API. See the authentication documentation for details.
Authorization
Bearer <token>
Parameters
| Name | Value |
|---|---|
| target | The target id for the target to analyse for flaky tests. Retrieve target ids from the Targets API. |
| from (optional) | Unix timestamp in milliseconds. Only runs created at or after this time are included in the analysis. |
| to (optional) | Unix timestamp in milliseconds. Only runs created at or before this time are included in the analysis. |
Response
Successful response:
{
"data": {
"code": 200,
"message": "Success",
"insight": {
"flaky_tests": [
{
"name": "Submit order",
"suite": "Checkout",
"failure_rate": 0.4,
"last_failure": 1700082800000,
"last_failure_iso": "2023-11-15T18:46:40.000Z",
"classification": "likely flaky"
}
]
}
}
}Failure response:
{
"error": {
"code": 400,
"message": "Missing parameter: target"
}
}Successful responses return JSON containing a data property. Error responses return JSON containing an error property. Both data and error values contain a code and message property, specifying the http status code and a message containing additional context.
Successful responses also contain an insight object with a flaky_tests array. Each entry contains the test name, suite, a failure_rate between 0 and 1, the last_failure timestamp in milliseconds, a last_failure_iso timestamp in ISO 8601 format, and a plain-language classification.
Regressions
Compares the latest run with its immediately preceding run, not the last passing run or a longer historical baseline. A failing test is new for this comparison if it previously passed or was absent; tests failing in both runs are continuing failures. Unknown-to-fail transitions are not classified as new failures by this endpoint.
With no preceding run, current failures are returned with a message that no baseline is available. The suspected_change_point is the latest build name, if available, not proof of the change that caused a failure.
This is useful for gating deployments, generating PR comments, or alerting on newly broken tests before they are lost among pre-existing failures.
curl https://www.tesults.com/api/insights/regressions
?target=target_id
-H "Authorization: Bearer token"
Endpoint
Headers
The Authorization header is required for all requests to the Tesults API. See the authentication documentation for details.
Authorization
Bearer <token>
Parameters
| Name | Value |
|---|---|
| target | The target id for the target to analyse for regressions. Retrieve target ids from the Targets API. |
Response
Successful response:
{
"data": {
"code": 200,
"message": "Success",
"insight": {
"new_failures": [
{
"name": "Submit order",
"suite": "Checkout",
"hash": "7c95f9b7-578d92c19fdd"
}
],
"continuing_failures": [
],
"impacted_tests": 1,
"baseline_comparison": "1 new failure vs previous run (build: 2.4.0).",
"suspected_change_point": "2.4.1"
}
}
}Failure response:
{
"error": {
"code": 400,
"message": "Missing parameter: target"
}
}Successful responses return JSON containing a data property. Error responses return JSON containing an error property. Both data and error values contain a code and message property, specifying the http status code and a message containing additional context.
Successful responses contain an insight object with new_failures for this comparison, continuing_failures present in both runs, impacted_tests (new failures only), a baseline_comparison description, and suspected_change_point containing the latest build name or null. New here does not mean the test has never failed before.
What changed
Returns a delta summary between a specified run and the previous run for the same target. The response lists tests that newly failed, tests that were previously failing and are now resolved, and any notable trends across the two runs.
This answers the question "what is different about this run compared to last time?" without requiring the caller to fetch and diff raw results data themselves.
curl https://www.tesults.com/api/insights/what-changed
?target=target_id
&run=run_id
-H "Authorization: Bearer token"
Endpoint
Headers
The Authorization header is required for all requests to the Tesults API. See the authentication documentation for details.
Authorization
Bearer <token>
Parameters
| Name | Value |
|---|---|
| target | The target id for the target that contains the run. Retrieve target ids from the Targets API. |
| run | The run id of the test run to compare against the previous run. Use the created_time value returned by the Results API as the run id, or retrieve it from the Tesults UI. |
Response
Successful response:
{
"data": {
"code": 200,
"message": "Success",
"insight": {
"delta_summary": "2 new failures, 1 resolved since the previous run.",
"new_failures": [
{
"name": "Submit order",
"suite": "Checkout",
"hash": "7c95f9b7-578d92c19fdd"
}
],
"resolved_failures": [
{
"name": "Load homepage",
"suite": "Navigation",
"hash": "3fa12c01-91ae74b20d11"
}
],
"continuing_failures": [
]
}
}
}Failure response:
{
"error": {
"code": 400,
"message": "Missing parameter: target"
}
}Successful responses return JSON containing a data property. Error responses return JSON containing an error property. Both data and error values contain a code and message property, specifying the http status code and a message containing additional context.
Successful responses also contain an insight object with a plain-language delta_summary, a new_failures array of tests that failed in this run but passed previously, a resolved_failures array of tests that previously failed but now pass, and a continuing_failures array of tests that failed in both this run and the previous run. Each test case entry includes name, suite, and hash.
Explain case
Returns a stability classification and history-based insight for a specific test case, analysing up to the last 10 runs in which the case appeared. The response mirrors the Test Case Insights panel shown in the Tesults UI.
This endpoint uses the case's recent history, not a history window ending at a selected historical run. Check runs_analyzed when interpreting its conclusions.
Use the hash value returned for a test case by the Results API as the case parameter. The hash uniquely identifies a test case across runs.
curl https://www.tesults.com/api/insights/explain-case
?target=target_id
&case=case_hash
-H "Authorization: Bearer token"
Endpoint
Headers
The Authorization header is required for all requests to the Tesults API. See the authentication documentation for details.
Authorization
Bearer <token>
Parameters
| Name | Value |
|---|---|
| target | The target id for the target that contains the test case. Retrieve target ids from the Targets API. |
| case | The hash of the test case to analyse. The hash is returned as the hash property for each test case in the Results API response and uniquely identifies a test case across runs. |
Response
Successful response:
{
"data": {
"code": 200,
"message": "Success",
"insight": {
"stability": "flaky",
"trend": "declining",
"summary": "Test alternates between pass and fail across recent runs.",
"confidence_score": 0.85,
"runs_analyzed": 10,
"patterns": [
{
"type": "flaky",
"description": "Result changes on every other run"
}
],
"recommendations": [
"Investigate timing dependency in checkout flow"
]
}
}
}Failure response:
{
"error": {
"code": 400,
"message": "Missing parameter: case"
}
}Successful responses return JSON containing a data property. Error responses return JSON containing an error property. Both data and error values contain a code and message property, specifying the http status code and a message containing additional context.
Successful responses also contain an insight object with a stability classification (stable, flaky, unstable, failing, degrading, or recovering), a trend (improving, stable, or declining), a plain-language summary, a confidence_score between 0 and 1, a runs_analyzed count, a patterns array of detected behavioural patterns, and a recommendations array of suggested actions.