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

# Create Replay Run

> Start a deterministic replay run against one or more voice clip sets.

A replay plays each selected clip set's recorded caller turns at the agent, turn by
turn, so the caller side is byte-identical between runs -- a metric delta is
attributable to a pipeline change rather than conversational variance. It places one
call per `(clip set, repetition)`, for `len(voice_clip_set_ids) * repeat_count` calls
total, and is inbound-only.

`selected_eval_ids` of `null` or `[]` means **no evals** -- a latency-only run. This
deliberately differs from Create Run, where `null` means "all evals": a benchmark run's
headline metric is latency, and silently scoring every eval would misrepresent what was
measured. Pass explicit eval IDs to grade the replayed calls.

Unlike Create Run, scenarios are written synchronously (no LLM involved -- each
scenario is a snapshot of one clip set's clips) and test calls are queued immediately,
so `generated_count` reflects the true total on the 202 response, not zero. Poll List
Runs for progress.



## OpenAPI

````yaml https://api.usetuner.ai/public/openapi.json post /api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs
openapi: 3.1.0
info:
  title: My Public API
  version: 1.0.0
servers:
  - url: https://api.usetuner.ai
security: []
tags:
  - name: calls
    x-group: Calls
  - name: workspaces
    x-group: Workspaces
  - name: simulation
    x-group: Simulation
  - name: agent-settings
    x-group: Agent Settings
  - name: agents
    x-group: Agents
  - name: traces
    x-group: Traces
  - name: providers
    x-group: Providers
paths:
  /api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs:
    post:
      tags:
        - simulation
      summary: Create Replay Run
      description: >-
        Start a deterministic replay run against one or more voice clip sets.


        A replay plays each selected clip set's recorded caller turns at the
        agent, turn by

        turn, so the caller side is byte-identical between runs -- a metric
        delta is

        attributable to a pipeline change rather than conversational variance.
        It places one

        call per `(clip set, repetition)`, for `len(voice_clip_set_ids) *
        repeat_count` calls

        total, and is inbound-only.


        `selected_eval_ids` of `null` or `[]` means **no evals** -- a
        latency-only run. This

        deliberately differs from Create Run, where `null` means "all evals": a
        benchmark run's

        headline metric is latency, and silently scoring every eval would
        misrepresent what was

        measured. Pass explicit eval IDs to grade the replayed calls.


        Unlike Create Run, scenarios are written synchronously (no LLM involved
        -- each

        scenario is a snapshot of one clip set's clips) and test calls are
        queued immediately,

        so `generated_count` reflects the true total on the 202 response, not
        zero. Poll List

        Runs for progress.
      operationId: >-
        create_replay_run_api_v1_workspaces__workspace_id__agents__agent_id__replay_runs_post
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: integer
            description: Tuner's internal numeric ID for the agent.
            title: Agent Id
          description: Tuner's internal numeric ID for the agent.
        - name: workspace_id
          in: path
          required: true
          schema:
            type: integer
            description: Workspace ID. Find this in Workspace > General Settings.
            title: Workspace Id
          description: Workspace ID. Find this in Workspace > General Settings.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReplayRunRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationRunResponse'
        '400':
          description: >-
            One or more `voice_clip_set_ids` are not `ready`, or do not belong
            to this agent.
          content:
            application/json:
              example:
                detail: >-
                  Voice clip set(s) [12, 13] are not ready, or do not belong to
                  this agent.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              example:
                detail: Not authenticated
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            The workspace has no credits remaining, or its plan does not include
            simulations.
          content:
            application/json:
              example:
                detail: You have no credits remaining.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have access to this workspace.
          content:
            application/json:
              example:
                detail: User does not have access to workspace 42
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Agent not found.
          content:
            application/json:
              example:
                detail: Agent with ID 17 not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A simulation run is already in progress for this agent.
          content:
            application/json:
              example:
                detail: You have a simulation run in progress. Come back later.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            The agent has no settings configured, is not inbound, its provider
            does not support simulations, or a selected clip set's worst-case
            call duration exceeds `max_call_duration_minutes`.
          content:
            application/json:
              example:
                detail: >-
                  Voice clip set 'Angry refund caller' (id=12) has a worst-case
                  call duration of 185000ms, which exceeds the 3-minute cap.
                  Increase max_call_duration_minutes.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Bearer: []
components:
  schemas:
    CreateReplayRunRequest:
      properties:
        voice_clip_set_ids:
          items:
            type: integer
          type: array
          maxItems: 10
          minItems: 1
          title: Voice Clip Set Ids
        repeat_count:
          type: integer
          maximum: 20
          minimum: 1
          title: Repeat Count
          default: 1
        max_call_duration_minutes:
          type: integer
          maximum: 12
          minimum: 1
          title: Max Call Duration Minutes
          default: 3
        selected_eval_ids:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Selected Eval Ids
        selected_intent_ids:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Selected Intent Ids
        replay_settings:
          anyOf:
            - $ref: '#/components/schemas/ReplaySettingsInput'
            - type: 'null'
      type: object
      required:
        - voice_clip_set_ids
      title: CreateReplayRunRequest
      description: >-
        Request to launch a deterministic replay run against one or more voice
        clip sets.
    SimulationRunResponse:
      properties:
        simulation_run_id:
          type: integer
          title: Simulation Run Id
        generated_count:
          type: integer
          title: Generated Count
        success:
          type: boolean
          title: Success
        caller_persona_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Caller Persona Id
        caller_persona:
          anyOf:
            - $ref: '#/components/schemas/CallerPersonaResponse'
            - type: 'null'
        simulation_profile_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Simulation Profile Id
        simulation_profile_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Simulation Profile Name
        simulation_profile_snapshot:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Simulation Profile Snapshot
        noise_environment_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Noise Environment Id
        noise_intensity:
          anyOf:
            - type: number
            - type: 'null'
          title: Noise Intensity
        noise_environment:
          anyOf:
            - $ref: '#/components/schemas/NoiseEnvironmentResponse'
            - type: 'null'
      type: object
      required:
        - simulation_run_id
        - generated_count
        - success
      title: SimulationRunResponse
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable description of what went wrong.
      type: object
      required:
        - detail
      title: ErrorResponse
      description: Error body returned when a request fails.
    ReplaySettingsInput:
      properties:
        silence_ms:
          anyOf:
            - type: integer
              maximum: 3000
              minimum: 200
            - type: 'null'
          title: Silence Ms
        min_speech_ms:
          anyOf:
            - type: integer
              maximum: 2000
              minimum: 50
            - type: 'null'
          title: Min Speech Ms
        inter_turn_delay_ms:
          anyOf:
            - type: integer
              maximum: 5000
              minimum: 0
            - type: 'null'
          title: Inter Turn Delay Ms
        max_wait_ms:
          anyOf:
            - type: integer
              maximum: 60000
              minimum: 1000
            - type: 'null'
          title: Max Wait Ms
        initial_agent_wait_ms:
          anyOf:
            - type: integer
              maximum: 60000
              minimum: 1000
            - type: 'null'
          title: Initial Agent Wait Ms
      type: object
      title: ReplaySettingsInput
      description: >-
        User-supplied overrides for a replay's timing policy.


        Every field is optional; an unset field falls back to the corresponding
        default on

        `app.services.simulation_clip_replay.ReplaySettings` -- the single
        source of truth

        for these defaults, deliberately not duplicated here.
    CallerPersonaResponse:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
        language:
          type: string
          title: Language
        language_code:
          type: string
          title: Language Code
        accent:
          type: string
          title: Accent
        label:
          type: string
          title: Label
        country_code:
          type: string
          title: Country Code
      type: object
      required:
        - id
        - name
        - language
        - language_code
        - accent
        - label
        - country_code
      title: CallerPersonaResponse
    NoiseEnvironmentResponse:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
          description: Display text, e.g. Café
        slug:
          type: string
          title: Slug
          description: Stable identifier, e.g. cafe
      type: object
      required:
        - id
        - name
        - slug
      title: NoiseEnvironmentResponse
      description: One selectable background environment.
  securitySchemes:
    Bearer:
      type: http
      description: >-
        Use Tuner API key (tr_api_...) or user session token. Find your API key
        in Workspace Settings > API Keys.
      scheme: bearer

````