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

# Run a test suite

> Starts a run of the suite against a chosen `agent_id` and returns immediately with a `pending` run; the Test Runner executes each scenario in the background (a durable Temporal workflow, or an in-process task when Temporal is disabled) and the dashboard Test Runner polls `GET /agent-test-runs/{run_id}` for progress and results. Every scenario must have a persona and the workspace must have credits. Scope `sessions:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /agent-test-suites/{suite_id}/runs
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /agent-test-suites/{suite_id}/runs:
    post:
      tags:
        - Agent Testing
      summary: Run a test suite
      description: >-
        Starts a run of the suite against a chosen `agent_id` and returns
        immediately with a `pending` run; the Test Runner executes each scenario
        in the background (a durable Temporal workflow, or an in-process task
        when Temporal is disabled) and the dashboard Test Runner polls `GET
        /agent-test-runs/{run_id}` for progress and results. Every scenario must
        have a persona and the workspace must have credits. Scope
        `sessions:write`.
      operationId: create_run_ca_api_v0_agent_test_suites__suite_id__runs_post
      parameters:
        - name: suite_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_id
              properties:
                agent_id:
                  type: string
                  description: >-
                    The agent to run the suite against. Chosen at run time
                    (suites are agent-agnostic); must exist in the workspace.
            example:
              agent_id: agent_sales_hi
      responses:
        '201':
          description: >-
            Run accepted; starts as `pending` and transitions to `running` then
            `passed`/`failed`/`error`. Poll the run to watch progress.
          content:
            application/json:
              example:
                id: test_run_01hzyb3c5d6e7f8g9h0j1k2l3m
                suite_id: test_suite_01hzy8x2m4q7r8s9t0v1w2x3y4
                agent_id: agent_sales_hi
                status: pending
                prompt_fingerprint: 9f2c1a7b4e6d8f0a1b2c3d4e5f607182
                total_scenarios: 3
                passed_scenarios: 0
                pass_rate: null
                cost_credits: 0
                temporal_workflow_id: null
                error: null
                created_at: '2026-05-22T10:05:00Z'
                updated_at: '2026-05-22T10:05:00Z'
        '400':
          description: >-
            `agent_id` missing or not in the workspace, the suite has no
            scenarios, or a scenario is missing its persona.
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  message: Add a persona to scenario 2 before running the suite.
        '401':
          description: Missing or invalid credentials (code `unauthorized`).
        '402':
          description: Workspace is out of credits.
          content:
            application/json:
              example:
                error:
                  code: insufficient_credits
                  message: >-
                    Workspace is out of credits. Add credits before running a
                    test.
        '403':
          description: >-
            The credential is missing the required `sessions:write` scope (code
            `forbidden`).
        '404':
          description: No suite with this id in the workspace.
          content:
            application/json:
              example:
                error:
                  code: not_found
                  message: Test suite not found
        '500':
          description: Unexpected server error (code `internal_error`).
        '503':
          description: Test orchestration (Temporal) could not be reached to start the run.
          content:
            application/json:
              example:
                error:
                  code: service_unavailable
                  message: >-
                    Test orchestration is temporarily unavailable. Please try
                    again.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````