Introduction - Empirical

The Test Runs API allows you to programmatically trigger test runs, retrieve their status, and manage their lifecycle.

Authentication

All endpoints require authentication using a Bearer token. Generate an API key from the dashboard.

Authorization: Bearer $EMPIRICALRUN_KEY

https://dash.empirical.run/api

Test runs transition through the following states:

State	Description
`pending`	Run is queued behind other runs (concurrency limit reached)
`queued`	Run is queued and will start soon
`started`	Run is currently executing
`ended`	Run completed successfully
`error`	Run failed with an error
`cancelling`	Run is being cancelled
`cancelled`	Run was cancelled

When a test run fails, it may include one of these error codes:

Error Code	Description
`merge_conflict`	Merge conflict detected when merging test branch
`dispatch_failed`	Failed to dispatch the test run to workers
`report_not_generated`	Test report was not generated
`run_failed_with_error`	Test run failed with an error during execution
`worker_interrupted`	Test run worker was interrupted
`merge_reports_failed`	Failed to merge sharded reports