> ## 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.

# Get Run

> Get one simulation run with its test calls and results.

The same run as in List Runs, plus `is_terminal` and a `dashboard_url`. Poll this until
`is_terminal` is true.



## OpenAPI

````yaml https://api.usetuner.ai/public/openapi.json get /api/v1/workspaces/{workspace_id}/agents/{agent_id}/simulation-runs/{run_id}
openapi: 3.1.0
info:
  title: Tuner API
  description: >-
    Send calls to Tuner and manage agents, evaluation settings, simulations and
    workspace settings.
  version: 1.0.0
servers:
  - url: https://api.usetuner.ai
security: []
tags:
  - name: calls
    description: Send call recordings and transcripts to Tuner and retrieve call details.
    x-group: Calls
  - name: workspaces
    description: >-
      Manage your workspaces, the API keys used to access them, and their PII
      redaction and data retention settings.
    x-group: Workspaces
  - name: simulation
    description: >-
      Run simulated calls against your agents, manage simulation profiles, and
      look up the caller personas and background-noise environments they can
      use.
    x-group: Simulation
  - name: scenarios
    description: Manage the test scenarios that simulated calls follow.
    x-group: Scenarios
  - name: replay-testing
    description: >-
      Replay recorded caller audio against a new version of your agent: upload
      or extract voice clips from real calls, then run them as replay runs.
    x-group: Replay Testing
  - name: agents
    description: Create, update and list the voice agents connected to your workspace.
    x-group: Agents
  - name: agent-settings
    description: >-
      Configure how Tuner evaluates an agent's calls, including evaluations,
      call outcomes, intents, data extraction, rules and alerts, plus the
      agent's SIP and outbound call configuration.
    x-group: Agent Settings
  - name: traces
    description: Send OpenTelemetry traces from your agent to Tuner.
    x-group: Traces
  - name: providers
    description: List the voice providers Tuner can connect to.
    x-group: Providers
paths:
  /api/v1/workspaces/{workspace_id}/agents/{agent_id}/simulation-runs/{run_id}:
    get:
      tags:
        - simulation
      summary: Get Run
      description: >-
        Get one simulation run with its test calls and results.


        The same run as in List Runs, plus `is_terminal` and a `dashboard_url`.
        Poll this until

        `is_terminal` is true.
      operationId: >-
        get_simulation_run_api_v1_workspaces__workspace_id__agents__agent_id__simulation_runs__run_id__get
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: integer
            description: ID of the simulation run.
            title: Run Id
          description: ID of the simulation run.
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            description: >-
              Tuner's numeric agent ID, or your Agent ID from Agent Settings >
              Agent Connection. Digits-only values are read as the numeric ID.
            title: Agent Id
          description: >-
            Tuner's numeric agent ID, or your Agent ID from Agent Settings >
            Agent Connection. Digits-only values are read as the numeric ID.
        - 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.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationRunGetResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              example:
                code: invalid_api_key
                detail: Not authenticated
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have access to this workspace.
          content:
            application/json:
              example:
                code: insufficient_access
                detail: User does not have access to workspace 42
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            The agent was not found, or the run is not one of this agent's
            simulation runs (replay runs included).
          content:
            application/json:
              examples:
                Agent not found:
                  summary: Agent not found
                  value:
                    code: agent_not_found
                    detail: Agent with ID 17 not found
                Run not found:
                  summary: Run not found
                  value:
                    code: run_not_found
                    detail: Simulation run with ID 4821 not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - Bearer: []
components:
  schemas:
    SimulationRunGetResponse:
      properties:
        id:
          type: integer
          title: Id
          description: ID of the simulation run.
        status:
          type: string
          title: Status
          description: >-
            Run status: `pending`, `running`, `analyzing`, `complete`,
            `partial`, `failed`, `unreported` or `analysis_failed`. `complete`
            means every call finished and was analyzed. `running` means calls
            are still executing, or have finished but none has been received
            yet. `analyzing` means calls have finished executing and some are
            still being reported or evaluated. `failed`, `unreported` and
            `analysis_failed` mean no call was analyzed, because every call
            failed, no call report arrived, or analysis failed, respectively.
            `failed` is also used when scenario generation fails; see
            `failure_reason`. `partial` is a mix of these.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the run was created.
        execution_completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Execution Completed At
          description: >-
            When every call finished executing. Null while calls are still in
            progress. The run can remain `running` or `analyzing` after this
            while calls are reported and evaluated.
        failure_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Reason
          description: Explanation of why the run failed. Null if it did not fail.
        functional_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Functional Count
          description: >-
            Number of functional scenarios requested. Null for runs from saved
            scenarios.
        adversarial_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Adversarial Count
          description: >-
            Number of adversarial scenarios requested. Null for runs from saved
            scenarios.
        generated_count:
          type: integer
          title: Generated Count
          description: Number of test scenarios created so far.
        caller_persona_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Caller Persona Id
          description: ID of the caller persona used. Null for replay runs.
        caller_persona:
          anyOf:
            - $ref: '#/components/schemas/CallerPersonaResponse'
            - type: 'null'
          description: The caller persona used. Null for replay runs.
        simulation_profile_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Simulation Profile Id
          description: ID of the simulation profile used, if one was given.
        simulation_profile_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Simulation Profile Name
          description: Name of the simulation profile used, if one was given.
        simulation_profile_snapshot:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Simulation Profile Snapshot
          description: Copy of the profile's fields as they were when the run started.
        noise_environment_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Noise Environment Id
          description: ID of the background-noise environment used, if one was given.
        noise_intensity:
          anyOf:
            - type: number
            - type: 'null'
          title: Noise Intensity
          description: Gain applied to the background noise, if noise was used.
        noise_environment:
          anyOf:
            - $ref: '#/components/schemas/NoiseEnvironmentResponse'
            - type: 'null'
          description: The background-noise environment used, if one was given.
        scenario_source:
          type: string
          enum:
            - generated
            - recorded_clips
          title: Scenario Source
          description: >-
            `generated` for generated and saved-scenario runs, `recorded_clips`
            for replay runs.
          default: generated
        voice_clip_sets:
          items:
            $ref: '#/components/schemas/VoiceClipSetRef'
          type: array
          title: Voice Clip Sets
          description: Voice clip sets played by a replay run. Empty otherwise.
        replay_repeat_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Replay Repeat Count
          description: >-
            Number of times each clip set was replayed. Null for non-replay
            runs.
        replay_settings:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Replay Settings
          description: Turn-timing overrides the replay used. Null for non-replay runs.
        evals_expected:
          type: boolean
          title: Evals Expected
          description: >-
            Whether the calls are graded by evals. False only for replay runs
            started without evals.
          default: true
        selected_evals:
          items:
            $ref: '#/components/schemas/CriteriaItem'
          type: array
          title: Selected Evals
          description: The evals the calls are graded with. Empty if none were selected.
        selected_intents:
          items:
            $ref: '#/components/schemas/CriteriaItem'
          type: array
          title: Selected Intents
          description: The call intents detected on the calls. Empty if none were selected.
        passed_count:
          type: integer
          title: Passed Count
          description: Number of calls that passed their evals.
        failed_count:
          type: integer
          title: Failed Count
          description: Number of calls that failed their evals.
        in_progress_count:
          type: integer
          title: In Progress Count
          description: >-
            Number of calls still waiting for results (not yet finished or
            evaluated).
        ran_count:
          type: integer
          title: Ran Count
          description: >-
            Number of calls that completed in a run started without evals, so
            there was nothing to grade them.
          default: 0
        unreported_count:
          type: integer
          title: Unreported Count
          description: Number of calls that completed but whose call data never arrived.
          default: 0
        analysis_failed_count:
          type: integer
          title: Analysis Failed Count
          description: Number of calls that arrived but whose evals never came back.
          default: 0
        simulation_calls:
          items:
            $ref: '#/components/schemas/SimulationCallDetailResponse'
          type: array
          title: Simulation Calls
          description: The simulated calls in the run, one per scenario.
        result:
          $ref: '#/components/schemas/RunResult'
          description: >-
            Overall result: `pending` until the run is terminal; then `failed`
            if any scenario failed, `inconclusive` if any scenario could not be
            judged, else `passed`.
        reason:
          anyOf:
            - $ref: '#/components/schemas/FailureCategory'
            - type: 'null'
          description: >-
            `agent_failed` when `result` is `failed`, `tuner_error` when
            `inconclusive`, null otherwise.
        run_mode:
          type: string
          title: Run Mode
          description: >-
            `generate` for runs with generated scenarios, `select` for library
            scenarios.
          default: generate
        is_terminal:
          type: boolean
          title: Is Terminal
          description: >-
            Whether the run has finished: `complete`, `partial`, `failed`,
            `unreported` or `analysis_failed`. `analyzing` is not terminal.
        dashboard_url:
          type: string
          title: Dashboard Url
          description: Link to the run in the Tuner dashboard.
      type: object
      required:
        - id
        - status
        - created_at
        - failure_reason
        - functional_count
        - adversarial_count
        - generated_count
        - caller_persona_id
        - caller_persona
        - selected_evals
        - selected_intents
        - passed_count
        - failed_count
        - in_progress_count
        - simulation_calls
        - result
        - reason
        - is_terminal
        - dashboard_url
      title: SimulationRunGetResponse
      description: One simulation run, as in List Runs, plus what a poller needs.
    ErrorResponse:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: Machine-readable error code. Branch on this, not on `detail`.
        detail:
          type: string
          title: Detail
          description: Human-readable description of what went wrong.
      type: object
      required:
        - code
        - detail
      title: ErrorResponse
      description: Error body returned when a request fails.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CallerPersonaResponse:
      properties:
        id:
          type: integer
          title: Id
          description: >-
            Persona ID. Pass as `caller_persona_id` when creating a simulation
            run.
          examples:
            - 1
        name:
          type: string
          title: Name
          description: Display name of the persona.
          examples:
            - English (British)
        language:
          type: string
          title: Language
          description: Language name.
          examples:
            - English
        language_code:
          type: string
          title: Language Code
          description: Language code.
          examples:
            - en
        accent:
          type: string
          title: Accent
          description: Accent identifier.
          examples:
            - British
        label:
          type: string
          title: Label
          description: Short accent label for display.
          examples:
            - UK
        country_code:
          type: string
          title: Country Code
          description: ISO 3166-1 alpha-2 country code of the accent.
          examples:
            - GB
        code:
          type: string
          title: Code
          description: >-
            Persona code, `<language_code>-<country_code>`. Accepted as
            `language` when starting a run.
          readOnly: true
          examples:
            - en-GB
      type: object
      required:
        - id
        - name
        - language
        - language_code
        - accent
        - label
        - country_code
        - code
      title: CallerPersonaResponse
      description: >-
        A caller persona: the language and accent a simulated caller speaks
        with.
    NoiseEnvironmentResponse:
      properties:
        id:
          type: integer
          title: Id
          description: >-
            Environment ID. Pass as `noise_environment_id` when creating a
            simulation run.
          examples:
            - 1
        name:
          type: string
          title: Name
          description: Display name of the environment.
          examples:
            - Café
        slug:
          type: string
          title: Slug
          description: Stable text identifier of the environment.
          examples:
            - cafe
      type: object
      required:
        - id
        - name
        - slug
      title: NoiseEnvironmentResponse
      description: One selectable background environment.
    VoiceClipSetRef:
      properties:
        id:
          type: integer
          title: Id
          description: ID of the voice clip set.
        name:
          type: string
          title: Name
          description: Name of the voice clip set when the run started.
      type: object
      required:
        - id
        - name
      title: VoiceClipSetRef
      description: A voice clip set played by a replay run, as it was when the run started.
    CriteriaItem:
      properties:
        id:
          type: integer
          title: Id
          description: ID of the eval or intent.
        name:
          type: string
          title: Name
          description: Name of the eval or intent.
      type: object
      required:
        - id
        - name
      title: CriteriaItem
      description: An eval or call intent a run was configured with.
    SimulationCallDetailResponse:
      properties:
        id:
          type: integer
          title: Id
          description: >-
            ID of the simulated call. Falls back to the scenario ID if the call
            has not been placed yet.
        scenario_id:
          type: integer
          title: Scenario Id
          description: ID of the scenario the call was placed for.
        type:
          type: string
          title: Type
          description: >-
            Scenario type, such as `functional`, `adversarial` or
            `recorded_clips`.
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: >-
            Status of the simulated call: `initiated`, `in_progress`,
            `completed` or `failed`. Null if the call has not been placed yet.
        duration:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration
          description: Duration of the simulated call, in minutes. Null if not available.
        outcome:
          anyOf:
            - $ref: '#/components/schemas/OutcomeDetail'
            - type: 'null'
          description: Call outcome detected on the call. Null if none was detected.
        intent:
          anyOf:
            - type: string
            - type: 'null'
          title: Intent
          description: Call intent detected on the call. Null if none was detected.
        evals:
          items:
            $ref: '#/components/schemas/SimulationCallEvalResult'
          type: array
          title: Evals
          description: Eval results for the call. Empty until evals have been reported.
        call_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Call Id
          description: >-
            ID of the resulting call, once it has reached Tuner. Null until
            then.
        analysis_stopped:
          type: boolean
          title: Analysis Stopped
          description: Whether the call outcome is one that stops further analysis.
          default: false
        unreported:
          type: boolean
          title: Unreported
          description: Whether the call completed but no call data ever arrived.
          default: false
        analysis_failed:
          type: boolean
          title: Analysis Failed
          description: Whether the call arrived but its evals never came back.
          default: false
        failure:
          anyOf:
            - $ref: '#/components/schemas/SimulationCallFailure'
            - type: 'null'
          description: >-
            Why the call, or its scenario before any call was placed, failed.
            Null unless it failed.
        target_eval_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Eval Label
          description: Name of the eval or call outcome the scenario targeted in this call.
        target_ai_evaluation:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Target Ai Evaluation
          description: The eval or call outcome the scenario targets. Null if it has none.
        clip_set_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Clip Set Name
          description: Name of the voice clip set played. Null for non-replay runs.
        repetition:
          anyOf:
            - type: integer
            - type: 'null'
          title: Repetition
          description: >-
            1-based repetition of the clip set that this call replayed. Null for
            non-replay runs.
        saved_scenario_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Saved Scenario Id
          description: >-
            ID of the library scenario this call's scenario was saved as. Null
            if it has not been saved to the library.
        persona:
          anyOf:
            - type: string
            - type: 'null'
          title: Persona
          description: >-
            Label of the scenario: the generated persona, or the library
            scenario's name for runs from saved scenarios. Null if not
            available, and for replay runs.
        verdict:
          $ref: '#/components/schemas/Verdict'
          description: >-
            Outcome of the scenario: `passed`, `failed` (an eval failed),
            `not_connected` (the call never connected), `platform_error`
            (something went wrong on Tuner's side), `unreported` (no call data
            arrived), `analysis_failed` (evals never came back), `ran` (finished
            in a run without evals), or `pending` (not finished yet).
        failure_category:
          anyOf:
            - $ref: '#/components/schemas/FailureCategory'
            - type: 'null'
          description: >-
            `agent_failed` for a `failed` verdict; `tuner_error` for
            `not_connected`, `platform_error`, `unreported` and
            `analysis_failed`; null otherwise.
        failed_evals:
          items:
            $ref: '#/components/schemas/FailedEval'
          type: array
          title: Failed Evals
          description: >-
            The evals that made the verdict `failed`. For an adversarial
            scenario with a target eval, only that eval. Empty for every other
            verdict.
      type: object
      required:
        - id
        - scenario_id
        - type
        - status
        - duration
        - outcome
        - intent
        - evals
        - call_id
        - verdict
        - failure_category
        - failed_evals
      title: SimulationCallDetailResponse
      description: A simulated call within a run, with its status and results.
    RunResult:
      type: string
      enum:
        - passed
        - failed
        - inconclusive
        - pending
      title: RunResult
    FailureCategory:
      type: string
      enum:
        - agent_failed
        - tuner_error
      title: FailureCategory
    ErrorCode:
      type: string
      enum:
        - invalid_api_key
        - insufficient_access
        - insufficient_credits
        - workspace_not_found
        - agent_not_found
        - scenario_not_found
        - run_not_found
        - no_scenarios_for_tag
        - run_too_large
        - unresolved_name
        - run_in_flight
        - simulation_not_configured
        - run_start_failed
        - rate_limited
        - validation_error
        - internal_error
      title: ErrorCode
      description: Machine-readable `code` on every error response.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    OutcomeDetail:
      properties:
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
          description: Name of the detected call outcome.
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: Type of the detected call outcome.
      type: object
      required:
        - value
        - type
      title: OutcomeDetail
      description: The outcome detected on a simulated call.
    SimulationCallEvalResult:
      properties:
        label:
          type: string
          title: Label
          description: Name of the eval.
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
          description: Result of the eval. Null if it produced no value.
        evidence:
          anyOf:
            - type: string
            - type: 'null'
          title: Evidence
          description: Explanation of the result. Null if none was given.
      type: object
      required:
        - label
        - value
        - evidence
      title: SimulationCallEvalResult
      description: The result of one eval on a simulated call.
    SimulationCallFailure:
      properties:
        reason:
          type: string
          title: Reason
        title:
          type: string
          title: Title
        message:
          type: string
          title: Message
      type: object
      required:
        - reason
        - title
        - message
      title: SimulationCallFailure
      description: Why a simulation call failed, in words safe to show a customer.
    Verdict:
      type: string
      enum:
        - passed
        - failed
        - not_connected
        - platform_error
        - unreported
        - analysis_failed
        - ran
        - pending
      title: Verdict
    FailedEval:
      properties:
        name:
          type: string
          title: Name
          description: Name of the eval.
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
          description: Result of the eval, such as `FAIL`.
      type: object
      required:
        - name
        - value
      title: FailedEval
      description: An eval that failed the scenario.
  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

````

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