> ## Documentation Index
> Fetch the complete documentation index at: https://empirical.run/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get test run metadata

> Returns Postgres-backed metadata for a test run. This endpoint does not read the run ledger or compose per-test results.



## OpenAPI

````yaml /api-reference/openapi.generated.json get /api/v2/test-runs/{id}
openapi: 3.1.0
info:
  title: Empirical API
  version: 1.0.0
  description: Programmatic access to Empirical test runs, snoozes, and more.
  contact:
    name: Empirical
    url: https://empirical.run
servers:
  - url: https://api.empirical.run
security:
  - Bearer: []
tags:
  - name: Test Runs
    description: Trigger, list, and inspect end-to-end test runs.
  - name: Test Cases
    description: >-
      Browse the Playwright test cases synced from a project's repository and
      manage their tags.
  - name: Environments
    description: >-
      Named deployment targets (slug + Playwright project filters) a project's
      tests run against.
  - name: Snoozes
    description: Temporarily suppress known test failures for specific Playwright tests.
  - name: Analytics
    description: Aggregated test-run, test-count and test-case analytics for a project.
  - name: Badges
    description: Public README status badge images (SVG) for project environments.
  - name: Failure Groups
    description: >-
      Durable, cross-run identities for failure modes, carrying the latest
      triage diagnosis.
  - name: Files
    description: >-
      Upload files of any type and get a link to use in tasks, sessions and
      messages. Agents should use the `upload_file` tool, which returns a
      project-wide `file@<id>` handle (`<id>` is the file `id` below).
  - name: Reporter Configuration
    description: Reporters a project can use in environment and run reporter configs.
paths:
  /api/v2/test-runs/{id}:
    get:
      tags:
        - Test Runs
      summary: Get test run metadata
      description: >-
        Returns Postgres-backed metadata for a test run. This endpoint does not
        read the run ledger or compose per-test results.
      operationId: getTestRunV2
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 2147483647
            description: Test run database ID.
          required: true
          description: Test run database ID.
          name: id
          in: path
      responses:
        '200':
          description: The test run metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTestRunV2Response'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Test run not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GetTestRunV2Response:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              description: Test run database ID.
            project_id:
              type: integer
              description: Owning project ID.
            state:
              type: string
              nullable: true
              description: Current run state.
            run_id:
              type: integer
              nullable: true
              description: External run identifier, if one was assigned.
            total_count:
              type: integer
              nullable: true
            unique_count:
              type: integer
              nullable: true
            success_count:
              type: integer
              nullable: true
            failed_count:
              type: integer
              nullable: true
            failed_count_after_snoozing:
              type: integer
              nullable: true
            skipped_count:
              type: integer
              nullable: true
            flaky_count:
              type: integer
              nullable: true
            duration:
              type: number
              nullable: true
            created_at:
              type: string
              nullable: true
            run_started_at:
              type: string
              nullable: true
            run_ended_at:
              type: string
              nullable: true
            test_run_branch:
              type: string
            test_run_head_sha:
              type: string
              nullable: true
            summary_url:
              type: string
              nullable: true
            environment_id:
              type: integer
              nullable: true
              description: Environment ID, if one was selected.
            environment_slug:
              type: string
              nullable: true
              description: Environment slug, if one was selected.
            environment_name:
              type: string
              nullable: true
              description: Environment name, if one was selected.
            environment_variables_overrides:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
                required:
                  - name
                  - value
              description: Per-run environment variable overrides.
            build_url:
              type: string
              nullable: true
            build_branch:
              type: string
              nullable: true
            commit:
              type: string
              nullable: true
            repo:
              type: string
              nullable: true
            error_code:
              type: string
              nullable: true
            cancellation_reason:
              type: string
              nullable: true
            cancelled_by_user_id:
              type: string
              nullable: true
            superseded_by_test_run_id:
              type: integer
              nullable: true
          required:
            - id
            - project_id
            - state
            - run_id
            - total_count
            - unique_count
            - success_count
            - failed_count
            - failed_count_after_snoozing
            - skipped_count
            - flaky_count
            - duration
            - created_at
            - run_started_at
            - run_ended_at
            - test_run_branch
            - test_run_head_sha
            - summary_url
            - environment_id
            - environment_slug
            - environment_name
            - environment_variables_overrides
            - build_url
            - build_branch
            - commit
            - repo
            - error_code
            - cancellation_reason
            - cancelled_by_user_id
            - superseded_by_test_run_id
          description: Response payload.
      required:
        - data
    ErrorResponse:
      type: object
      properties:
        data:
          nullable: true
          description: Always null for error responses.
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message.
          required:
            - message
          description: Error details.
      required:
        - data
        - error
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.