# Empirical - [Introduction](https://empirical.run/docs/index.md): Understand how Empirical creates, runs, and maintains end-to-end tests - [Tasks](https://empirical.run/docs/platform/tasks.md): Ask Empirical agents to add or update test coverage - [CLI](https://empirical.run/docs/cli.md): Install the empirical command line tool, sign in, and set up the agent skill for Claude Code, Codex and other coding agents - [Environments](https://empirical.run/docs/platform/environments.md): Configure deployment targets, test selection, variables, and schedules - [Test repository](https://empirical.run/docs/platform/repository.md): Clone and work with the Playwright tests Empirical maintains - [Repository settings](https://empirical.run/docs/platform/repository-settings.md): GitHub settings Empirical needs to open and merge pull requests in your test repository - [Snoozes](https://empirical.run/docs/platform/snoozes.md): Suppress known test failures in reports and status checks while you work on a fix, for a set time or until you end it - [Memories](https://empirical.run/docs/platform/memories.md): Durable knowledge about your product that guides test generation agents - [Test run configuration](https://empirical.run/docs/platform/test-run-configuration.md): Where test runs execute, how they shard across workers, and which reporters post their results - [Private Runner](https://empirical.run/docs/platform/private-runner.md): Run test runs on infrastructure in your own AWS account (BYOC) - [Branching](https://empirical.run/docs/features/branching.md): Run feature-branch test changes against preview deployments, and merge them when the application branch merges - [Linked test changes](https://empirical.run/docs/features/linked-test-changes.md): Block an app pull request until its test changes are merged - [Concurrency](https://empirical.run/docs/features/concurrency-limits.md): Control what happens when a test run is triggered while another run in the same group is still going - [Analytics](https://empirical.run/docs/features/analytics.md): Track pass, fail and flaky rates for every test over time, and filter tests with a search syntax that also works in the API - [Code coverage](https://empirical.run/docs/features/code-coverage.md): Measure which parts of your application code the end-to-end tests exercise, as an Istanbul HTML report - [Slack notifications](https://empirical.run/docs/features/slack-notifications.md): Mention the owners of failing tests in Slack run notifications, with ownership rules by tag, file or directory - [Email testing](https://empirical.run/docs/features/email-testing.md): Receive real emails in Playwright tests to check OTP codes, invitation links and notification emails - [Webhook testing](https://empirical.run/docs/features/webhook-testing.md): Capture the webhooks your application sends during a test, assert on their payloads, and inspect each request - [KV store](https://empirical.run/docs/features/kv-store.md): Share state across tests, shards, test runs and agent sessions - [Slack](https://empirical.run/docs/integrations/slack.md): Get test run reports in Slack channels, and mention the @Empirical bot to start an agent session from any thread - [GitHub Reporter](https://empirical.run/docs/integrations/github.md): See test run results on your pull requests and commits as GitHub comments and status checks you can require - [Linear](https://empirical.run/docs/integrations/linear.md): Assign a Linear issue to the Empirical agent to create a coverage task that agents start working on right away - [Jira](https://empirical.run/docs/integrations/jira.md): Add the empirical label to a Jira ticket to create a coverage task that agents start working on right away - [From CI/CD pipelines](https://empirical.run/docs/triggers/ci-cd.md): Trigger a test run from GitHub Actions or any CI/CD provider after a deployment, with build metadata, variables and concurrency - [Scheduled runs](https://empirical.run/docs/triggers/scheduled.md): Run an environment automatically using a UTC cron schedule - [Ad-hoc runs](https://empirical.run/docs/triggers/ad-hoc.md): Trigger a one-off test run from the dashboard, CLI, or API - [CLI reference](https://empirical.run/docs/cli-reference.md): Arguments, options and examples for every empirical command, from signing in to calling the API and reading the KV store. - [Deprecations](https://empirical.run/docs/deprecations.md): Fields, inputs and settings Empirical has replaced, what each one does if you still send it, and what to use instead - [Introduction](https://empirical.run/docs/api-reference/introduction.md): Base URL, authentication and versioning for the Empirical API, with a project API key or your CLI sign-in - [List test runs](https://empirical.run/docs/api-reference/test-runs/list-test-runs.md): Returns a paginated list of test runs for the scoped project, with optional filtering by id, branch, state, result, environment, and time window. - [Trigger a test run](https://empirical.run/docs/api-reference/test-runs/trigger-a-test-run.md): Triggers a new end-to-end test run for the scoped project, optionally with a saved environment, resolving the branch/build and dispatching the run. - [Get a test run](https://empirical.run/docs/api-reference/test-runs/get-a-test-run.md): Retrieves a single test run by ID, including its project and per-test summary details. Access is derived from the run's project; inaccessible or unknown runs return 404. - [List test run artifacts](https://empirical.run/docs/api-reference/test-runs/list-test-run-artifacts.md): Lists downloadable artifacts (traces, reports, screenshots, etc.) stored for a test run. Provide `key` for an exact lookup, or `prefix`/`suffix` to filter the listing. Returns an empty list when nothing matches. - [Cancel a test run](https://empirical.run/docs/api-reference/test-runs/cancel-a-test-run.md): Cancels an in-progress test run, recording an optional reason and the cancelling user. Returns 412 when the run is already in a terminal state. - [Re-run a test run](https://empirical.run/docs/api-reference/test-runs/re-run-a-test-run.md): Re-triggers a test run from a source run's branch, build, and overrides. Optionally re-runs only the failed tests of a completed run. - [Skip a test run](https://empirical.run/docs/api-reference/test-runs/skip-a-test-run.md): Marks the Empirical check run on a commit as skipped. Callers authenticate with a project API key. - [Get test run metadata](https://empirical.run/docs/api-reference/test-runs/get-test-run-metadata.md): Returns Postgres-backed metadata for a test run. This endpoint does not read the run ledger or compose per-test results. - [List test cases](https://empirical.run/docs/api-reference/test-cases/list-test-cases.md): Returns a paginated list of the scoped project's test cases with optional filtering, along with the project's latest test-cases sync error. - [Get a test case](https://empirical.run/docs/api-reference/test-cases/get-a-test-case.md): Retrieves a single test case by its Playwright test ID. Access is derived from the test case's project, returning 403 when the caller cannot access it. - [Update test case tags](https://empirical.run/docs/api-reference/test-cases/update-test-case-tags.md): Replaces the tags on a test case and attempts to update the source file. Access is derived from the test case's project, returning 403 when the caller cannot access it. - [List test case tags](https://empirical.run/docs/api-reference/test-cases/list-test-case-tags.md): Returns the distinct set of tags across the scoped project's active test cases (those present at the last synced commit; all synced test cases if the project has never synced). The response is a bare `{ tags }` object (no `data` envelope) and is cached for 5 minutes via a `Cache-Control` header. - [Create an environment](https://empirical.run/docs/api-reference/environments/create-an-environment.md): Creates an environment in the scoped project. Rejected for projects managed by environments.yaml. - [Delete an environment](https://empirical.run/docs/api-reference/environments/delete-an-environment.md): Deletes an environment by ID and prunes environment-specific subscriptions. The project is derived from the entity. - [Update an environment](https://empirical.run/docs/api-reference/environments/update-an-environment.md): Updates an environment by ID. The project is derived from the entity. Returns the bare updated row (no `data` envelope), matching the dashboard settings UI it serves. - [List environments](https://empirical.run/docs/api-reference/environments/list-environments.md): Returns the scoped project's environments, optionally filtered by slug and disabled state. The run worker uses this to resolve env vars by slug. - [Sync environments from YAML](https://empirical.run/docs/api-reference/environments/sync-environments-from-yaml.md): Upserts the scoped project's environments from its environments.yaml file and flags the project as YAML-managed. - [List snoozes](https://empirical.run/docs/api-reference/snoozes/list-snoozes.md): Returns a paginated list of snoozes for the scoped project, with optional filtering by environment and status. - [Create a snooze](https://empirical.run/docs/api-reference/snoozes/create-a-snooze.md): Creates a snooze to temporarily suppress failures for the given Playwright tests until `snooze_until`. - [Get a snooze](https://empirical.run/docs/api-reference/snoozes/get-a-snooze.md): Retrieves a single snooze by ID. - [Delete a snooze](https://empirical.run/docs/api-reference/snoozes/delete-a-snooze.md): Permanently deletes a snooze. - [Update a snooze](https://empirical.run/docs/api-reference/snoozes/update-a-snooze.md): Updates a snooze — extend it, change its tests/description, or expire it immediately with `expire_now`. - [Add tests to a snooze](https://empirical.run/docs/api-reference/snoozes/add-tests-to-a-snooze.md): Adds Playwright tests to an existing snooze. - [List KV entries](https://empirical.run/docs/api-reference/kv/list-kv-entries.md): Lists unexpired entries in key order, optionally filtered by key prefix. Values are omitted unless `include_values=true`; a page with values ends early once it holds about 8 MB, so always follow `next_cursor`. - [Get a KV entry](https://empirical.run/docs/api-reference/kv/get-a-kv-entry.md): Returns the entry stored under `key`, if it has not expired. - [Write a KV entry](https://empirical.run/docs/api-reference/kv/write-a-kv-entry.md): Creates or replaces the entry under `key` with a required TTL. Send `If-None-Match: *` to create only (e.g. acquire a lock) or `If-Match: ` to replace only an unchanged entry. - [Delete a KV entry](https://empirical.run/docs/api-reference/kv/delete-a-kv-entry.md): Deletes the entry under `key`. Send `If-Match: ` to delete only an unchanged entry (e.g. release a lock you still hold). - [Refresh a KV entry's TTL](https://empirical.run/docs/api-reference/kv/refresh-a-kv-entrys-ttl.md): Resets the entry's TTL without resending its value, e.g. to extend a lock lease. Send `If-Match: ` to refresh only an unchanged entry. - [Test-case execution history (batch)](https://empirical.run/docs/api-reference/analytics/test-case-execution-history-batch.md): Returns per-test-case execution history for the requested test cases, plus echoed query metadata. - [Last passing run per environment](https://empirical.run/docs/api-reference/analytics/last-passing-run-per-environment.md): Returns the most recent passing run for a test case, grouped by environment. - [Test-case analytics](https://empirical.run/docs/api-reference/analytics/test-case-analytics.md): Returns aggregated test-case metrics for the scoped project (without per-test history). - [Test-count analytics](https://empirical.run/docs/api-reference/analytics/test-count-analytics.md): Returns the number of distinct test cases run per day for the scoped project. - [Test-run analytics](https://empirical.run/docs/api-reference/analytics/test-run-analytics.md): Returns daily test-run statistics and a period summary for the scoped project. - [Get an environment status badge](https://empirical.run/docs/api-reference/badges/get-an-environment-status-badge.md): Renders an SVG status badge (passing/failing/running/etc.) for the latest test run of a project environment. Served unauthenticated for embedding in READMEs. - [List files](https://empirical.run/docs/api-reference/files/list-files.md): Returns the project's files, newest first. - [Create a file](https://empirical.run/docs/api-reference/files/create-a-file.md): Registers a file and returns its link plus a presigned `upload_url`. PUT the file body to `upload_url` with the same `Content-Type` as `mime_type`; the link serves the file once the upload finishes. - [Get a file](https://empirical.run/docs/api-reference/files/get-a-file.md): Returns one of the project's files by ID. - [Confirm a file upload](https://empirical.run/docs/api-reference/files/confirm-a-file-upload.md): Marks a file `uploaded` after its body was PUT to `upload_url`. Checks the content is in storage and records its size. Safe to repeat. - [Get static egress IPs for a region](https://empirical.run/docs/api-reference/infra/get-static-egress-ips-for-a-region.md): Returns the proxy endpoint and the egress IPs to allowlist for the given region. Requires the project's Static IP proxy add-on. - [List reporters](https://empirical.run/docs/api-reference/reporter-configuration/list-reporters.md): Lists the reporters a reporter config can name for the scoped project, with whether each can post: the organization's registered Slack channels, the GitHub check and PR comment with the repositories the GitHub Reporter app covers, the email report, and the run-only Slack DM to whoever starts the run… ## OpenAPI Specs - [openapi.generated](/docs/api-reference/openapi.generated.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.