Documentation
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
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, the root cause of failures, the number of failed tests, and the key failure patterns observed.
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.",
"root_cause": "Payment gateway timeout during order submission.",
"failed_count": 1,
"failure_patterns": [
"Timeout errors concentrated in Checkout suite"
]
}
}
}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 summary, a root_cause description, the number of failed_count tests, and a failure_patterns array listing the key patterns observed across the failing tests.
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".
Flaky tests are detected by tracking result changes across multiple runs. A test is considered flaky if its result alternates between pass and fail more than twice across the runs analysed. Use the optional from and to parameters to constrain the time window.
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
Returns newly introduced failures for a target by comparing the most recent run against a historical baseline. The response identifies which tests newly failed, the suspected change point (build or commit), and distinguishes new failures from pre-existing or flaky ones.
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": [
{... test cases failing in both runs}
],
"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 also contain an insight object with a new_failures array of tests that failed for the first time in the latest run, a continuing_failures array of tests that failed in both the latest and previous run, a count of impacted_tests (new failures only), a plain-language baseline_comparison string, and a suspected_change_point containing the build name of the latest run.
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": [
{... test cases failing in both runs}
]
}
}
}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.
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.