Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.empirical.run/llms.txt

Use this file to discover all available pages before exploring further.

The Analytics API provides access to aggregated test data that powers the Analytics page, enabling you to track test health, trends, and performance over time. Use this API to make custom views.

​
Authentication

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

​
Versioning

Analytics endpoints use path-based versioning. The current recommended version is v2, prefixed with /api/v2/analytics/. The earlier v1 endpoints (/api/v1/analytics/*) are deprecated but remain available for backward compatibility. New integrations should use v2. For backward compatibility, requests to the unversioned path /api/analytics/* are automatically redirected to /api/v1/analytics/*.

​
Migrating from v1 to v2

  • GET /api/v1/analytics/test-runs → GET /api/v2/analytics/test-runs (identical response shape).
  • GET /api/v1/analytics/test-count → GET /api/v2/analytics/test-count (identical response shape).
  • GET /api/v1/analytics/test-cases is split in v2 for performance:
    • GET /api/v2/analytics/test-cases returns metrics only (no history[]).
    • POST /api/v2/analytics/test-case-history/batch fetches history for one or many test cases in a single request.

​
Timestamp Format

All timestamps use ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ) in both request and response payloads. Example: 2025-02-01T10:30:00.000Z

​
Percentage Values

All percentage fields (e.g., pass_rate, fail_rate, flaky_rate) are integers in the 0-100 range, not decimals.

​
Date Filtering

All analytics endpoints support date filtering via query parameters:
ParameterTypeDescription
daysnumberNumber of days of history (1-90). Overridden if start_date and end_date are provided.
start_datestringStart of custom date range (ISO 8601). Must be used with end_date.
end_datestringEnd of custom date range (ISO 8601). Must be used with start_date.