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

# Get a simulated call

> Get a individual simulation run directly by its ID. This is generally part of a larger simulation run plan job.



## OpenAPI

````yaml /api-reference/openapi.documented.json get /v1/simulation/job/{jobId}
openapi: 3.1.0
info:
  title: Roark Analytics API
  description: >-
    The Roark Analytics API gives you access to the same API that powers the
    award winning Roark Analytics platform.
  version: 1.0.0
servers:
  - description: Production
    url: https://api.roark.ai
security:
  - Bearer: []
tags:
  - name: Health
    x-displayName: Health
  - name: Authentication
    x-displayName: Current credential
  - name: Project API Key
    x-displayName: Project API keys
  - name: Personal API Key
    x-displayName: Personal API keys
  - name: Agent
    x-displayName: Agents
  - name: Agent Endpoint
    x-displayName: Endpoints
  - name: Tool
    x-displayName: Tools
  - name: Agent Setup
    x-displayName: Automatic test setup
  - name: Autoimprove
    x-displayName: Autoimprove
  - name: Customer Flow
    x-displayName: Customer flows
  - name: Customer Flow Folder
    x-displayName: Customer flow folders
  - name: Simulation Persona
    x-displayName: Personas
  - name: Simulation Environment
    x-displayName: Environments
  - name: Simulation Template
    x-displayName: Templates
  - name: Simulation Run Plan
    x-displayName: Plans
  - name: Simulation Run
    x-displayName: Runs
  - name: Simulation Tool Mock
    x-displayName: Tool mocks and fixtures
  - name: Metric
    x-displayName: Definitions
  - name: Metric Variant
    x-displayName: Variants
  - name: Metric Policy
    x-displayName: Policies
  - name: Metric Collection Job
    x-displayName: Collection jobs
  - name: Call
    x-displayName: Calls
  - name: Chat
    x-displayName: Chats
  - name: Customer
    x-displayName: Customers
  - name: Issue
    x-displayName: Issues
  - name: Analytics
    x-displayName: Analytics
  - name: Dashboard
    x-displayName: Dashboards
  - name: Live Report
    x-displayName: Reports
  - name: Agent Connection
    x-displayName: Agent platforms
  - name: Calendar Connection
    x-displayName: Calendars
  - name: MCP Server Connection
    x-displayName: MCP servers
  - name: Knowledge Base
    x-displayName: Knowledge bases
  - name: HTTP Request Definition
    x-displayName: HTTP request definitions
  - name: Webhook
    x-displayName: Webhooks
  - name: Config
    x-displayName: Config as code
  - name: Organization Project
    x-displayName: Projects
  - name: Organization Project Member
    x-displayName: Project members
  - name: Usage
    x-displayName: Usage
  - name: Benchmark
    x-displayName: Benchmarks
paths:
  /v1/simulation/job/{jobId}:
    get:
      tags:
        - Simulation Run
      summary: Get a simulated call
      description: >-
        Get a individual simulation run directly by its ID. This is generally
        part of a larger simulation run plan job.
      operationId: getV1SimulationJobByJobId
      parameters:
        - in: path
          name: jobId
          schema:
            type: string
            format: uuid
          required: true
          example: 7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f
          description: Simulation job ID
      responses:
        '200':
          description: Successfully found simulation job
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SimulationJobResponse'
                required:
                  - data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Simulation job not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Roark from '@roarkanalytics/sdk';


            const client = new Roark({
              bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
            });


            const response = await
            client.simulationJob.getByID('7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f');


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from roark_analytics import Roark

            client = Roark(
                bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            response = client.simulation_job.get_by_id(
                "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f",
            )
            print(response.data)
components:
  schemas:
    SimulationJobResponse:
      type: object
      properties:
        simulationJobId:
          type: string
          format: uuid
          description: Simulation job ID
        status:
          type: string
          description: >-
            Job status. `RETRY_SCHEDULED` is a retry of a simulation your agent
            never spoke on, waiting out the plan’s
            `noResponseRetryBackoffSeconds` before it dials.
        processingStatus:
          type: string
          description: Processing status
        queuePosition:
          type:
            - integer
            - 'null'
          exclusiveMinimum: 0
          description: >-
            This simulation's 1-based place in its run's queue, in the order the
            queue releases simulations. Null unless the status is QUEUED.
        callId:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            ID of the call created for this simulation job. Null if the call has
            not been created yet.
        roarkPhoneNumber:
          type:
            - string
            - 'null'
          description: >-
            Phone number provisioned by Roark for this simulation job in E.164
            format. Null if the simulation job is queued and has not been
            assigned a phone number yet.
        runPlan:
          $ref: '#/components/schemas/SimulationRunPlanRef'
        enrichment:
          $ref: '#/components/schemas/SimulationJobEnrichment'
        invalidation:
          oneOf:
            - $ref: '#/components/schemas/SimulationJobInvalidation'
            - type: 'null'
          description: Null while the result counts. See SimulationJobInvalidation.
        failureOwner:
          type:
            - string
            - 'null'
          enum:
            - ROARK
            - AGENT
          description: >-
            Who a FAILED or TIMED_OUT job failed because of. Null when the job
            did not fail. `AGENT`: your agent under test did not answer, was
            busy, declined, hung up or went silent, or its outbound-dial HTTP
            endpoint refused. This is a real result. `ROARK`: the simulation
            itself failed on the Roark platform (pipeline, capacity or
            analysis). It says nothing about your agent, and the run report
            leaves these jobs out of every count.
        retryOfSimulationJobId:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The simulation this one retries, because your agent never spoke on
            it. Null on a test case’s first attempt.
        attemptNumber:
          type: integer
          exclusiveMinimum: 0
          description: >-
            This simulation’s place among its test case’s attempts: 1 for the
            first, 2 for the first retry. Above 1 only when the plan retries
            simulations your agent never spoke on.
        scheduledAt:
          type:
            - string
            - 'null'
          description: >-
            When a `RETRY_SCHEDULED` retry dials, ISO 8601. Null on a first
            attempt.
        persona:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier of the persona
            name:
              type: string
              description: The name the agent will identify as during conversations
            displayName:
              type:
                - string
                - 'null'
              description: >-
                Label shown in place of the name across the dashboard (e.g. a
                short descriptor like "Irate Escalator"). The persona still
                identifies as `name` on calls. Omit or set null to display the
                name itself.
            description:
              type:
                - string
                - 'null'
              description: Human-readable description of the persona
            language:
              type: string
              enum:
                - EN
                - ES
                - DE
                - HI
                - FR
                - NL
                - AR
                - EL
                - IT
                - ID
                - TH
                - JA
                - TL
                - MS
                - ZH
                - TR
                - PT
                - HE
              description: Primary language ISO 639-1 code for the persona
            secondaryLanguage:
              type:
                - string
                - 'null'
              enum:
                - EN
              description: >-
                Secondary language ISO 639-1 code for code-switching (e.g.,
                Hinglish, Spanglish)
            understoodLanguages:
              type: array
              items:
                type: string
                enum:
                  - EN
                  - ES
                  - DE
                  - HI
                  - FR
                  - NL
                  - AR
                  - EL
                  - IT
                  - ID
                  - TH
                  - JA
                  - TL
                  - MS
                  - ZH
                  - TR
                  - PT
                  - HE
              minItems: 1
              description: >-
                Languages the persona can understand. Multilingual combinations
                are limited by multilingual speech recognition support.
            accent:
              type: string
              enum:
                - US
                - US_X_SOUTH
                - GB
                - ES
                - DE
                - IN
                - FR
                - NL
                - SA
                - GR
                - AU
                - IT
                - ID
                - TH
                - JP
                - NZ
                - PH
                - SG
                - MY
                - HK
                - TR
                - PT
                - IL
              description: >-
                Accent of the persona, defined using ISO 3166-1 alpha-2 country
                codes with optional variants
            age:
              type: string
              enum:
                - CHILD
                - TEENAGER
                - ADULT
                - ELDERLY
              default: ADULT
              description: >-
                How old the caller sounds and behaves. Only ages the persona's
                accent has a voice for are accepted; defaults to ADULT, which
                every accent supports.
            gender:
              type: string
              enum:
                - MALE
                - FEMALE
              description: Gender of the persona
            backgroundNoise:
              type: string
              enum:
                - NONE
                - AIRPORT
                - CHILDREN_PLAYING
                - CITY
                - COFFEE_SHOP
                - CONSTRUCTION
                - CRYING_BABY
                - DRIVING
                - LIBRARY
                - OFFICE
                - THUNDERSTORM
                - TRAIN
              default: NONE
              description: Background noise setting
            speechPace:
              type: string
              enum:
                - SUPER_SLOW
                - SLOW
                - NORMAL
                - FAST
                - SUPER_FAST
              default: NORMAL
              description: Speech pace of the persona
            speechClarity:
              type: string
              enum:
                - CLEAR
                - VAGUE
                - RAMBLING
              default: CLEAR
              description: Speech clarity of the persona
            hasDisfluencies:
              type: boolean
              default: false
              description: Whether the persona uses filler words like "um" and "uh"
            baseEmotion:
              type: string
              enum:
                - NEUTRAL
                - CHEERFUL
                - CONFUSED
                - FRUSTRATED
                - SKEPTICAL
                - RUSHED
                - DISTRACTED
                - ANGRY
                - ANXIOUS
                - SAD
              default: NEUTRAL
              description: Base emotional state of the persona
            intentClarity:
              type: string
              enum:
                - CLEAR
                - INDIRECT
                - VAGUE
              default: CLEAR
              description: How clearly the persona expresses their intentions
            confirmationStyle:
              type: string
              enum:
                - EXPLICIT
                - VAGUE
              default: EXPLICIT
              description: How the persona confirms information
            memoryReliability:
              type: string
              enum:
                - HIGH
                - LOW
              default: HIGH
              description: How reliable the persona's memory is
            responseTiming:
              type: string
              enum:
                - RELAXED
                - NORMAL
                - QUICK
                - BARGE_IN
              default: NORMAL
              description: >-
                Deprecated and inert: it no longer affects the call. It set how
                long the persona waited once the agent stopped talking, and
                measured across production simulations it moved the reply gap by
                less than the noise floor, because model and speech latency
                dominate it. Every persona now uses one voice-activity profile.
                Use `interruption` for a caller who talks over the agent. Still
                accepted and stored so existing clients keep working. BARGE_IN
                is stored as `responseTiming: QUICK` with `interruption:
                OCCASIONAL`.
            interruption:
              type: string
              enum:
                - 'OFF'
                - BACKCHANNEL
                - OCCASIONAL
                - HEAVY
              default: 'OFF'
              description: >-
                How much the persona talks over the agent while it is still
                speaking. OFF waits its turn. BACKCHANNEL makes listening noises
                ("mm-hm") over the agent without taking the floor, which tests
                whether the agent wrongly stops for them. OCCASIONAL also cuts
                in where a caller like this plausibly would, and HEAVY does so
                readily, though never on every turn. The moments are chosen from
                what the agent is saying, such as reading back a number or
                starting a long explanation, not on a timer. A customer flow can
                also say exactly when to cut in, which applies at any level.
            backstoryPrompt:
              type:
                - string
                - 'null'
              description: Background story and behavioral patterns for the persona
              example: A busy professional calling during lunch break
            idleMessages:
              type:
                - array
                - 'null'
              items:
                type: string
              description: >-
                Messages the persona will say when the agent goes silent during
                a call. null = "Automatic": language-appropriate defaults are
                used at call time.
            idleTimeoutSeconds:
              type: integer
              minimum: 5
              maximum: 60
              default: 10
              description: Seconds of silence before the persona sends an idle message
            idleMessageMaxSpokenCount:
              type: integer
              minimum: 1
              maximum: 10
              default: 3
              description: >-
                Maximum number of idle messages the persona will send before
                giving up
            idleMessageResetCountOnUserSpeechEnabled:
              type: boolean
              default: true
              description: Whether the idle message counter resets when the agent speaks
            properties:
              type: object
              additionalProperties: {}
              default: {}
              description: Additional custom properties about the persona
              example:
                age: 35
                zipCode: '94105'
                occupation: Software Engineer
            phoneNumber:
              type: string
              description: >-
                The E.164 number every call with this persona uses, when Roark
                has pinned one for your project. Present only when set;
                read-only.
              example: '+19312830919'
            createdAt:
              type: string
              description: Creation timestamp
            updatedAt:
              type: string
              description: Last update timestamp
          required:
            - id
            - name
            - language
            - understoodLanguages
            - accent
            - age
            - gender
            - backgroundNoise
            - speechPace
            - speechClarity
            - hasDisfluencies
            - baseEmotion
            - intentClarity
            - confirmationStyle
            - memoryReliability
            - responseTiming
            - interruption
            - idleMessages
            - idleTimeoutSeconds
            - idleMessageMaxSpokenCount
            - idleMessageResetCountOnUserSpeechEnabled
            - properties
            - createdAt
            - updatedAt
        backgroundNoise:
          $ref: '#/components/schemas/SimulationJobBackgroundNoise'
        scenario:
          $ref: '#/components/schemas/ScenarioResponse'
        agentEndpoint:
          $ref: '#/components/schemas/AgentEndpointResponse'
        createdAt:
          type: string
          description: When the job was created
        startedAt:
          type:
            - string
            - 'null'
          description: When the job started
        completedAt:
          type:
            - string
            - 'null'
          description: When the job completed
      required:
        - simulationJobId
        - status
        - processingStatus
        - queuePosition
        - runPlan
        - enrichment
        - invalidation
        - failureOwner
        - retryOfSimulationJobId
        - attemptNumber
        - scheduledAt
        - persona
        - backgroundNoise
        - scenario
        - agentEndpoint
        - createdAt
      description: Simulation job with related entities
      example:
        simulationJobId: 7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f
        status: COMPLETED
        processingStatus: PROCESSED
        queuePosition: null
        callId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        roarkPhoneNumber: '+15551234567'
        runPlan:
          id: b2c3d4e5-f6a7-8901-bcde-f12345678901
          name: Billing Flow Test
          variables:
            promptToUse: v1
            accountTier: premium
        enrichment:
          requested: true
          outcome: TIMED_OUT
          waitStartedAt: '2025-01-15T14:28:32.789Z'
          waitEndedAt: '2025-01-15T14:43:32.789Z'
          metricsScoredOnSimulationInstead: 4
          metricsNotCollected: 1
        invalidation: null
        failureOwner: null
        retryOfSimulationJobId: null
        attemptNumber: 1
        scheduledAt: null
        persona:
          id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          name: Sarah Johnson - Anxious Patient
          displayName: Anxious Patient
          language: EN
          secondaryLanguage: null
          understoodLanguages:
            - EN
          accent: US
          age: ADULT
          gender: FEMALE
          backgroundNoise: OFFICE
          speechPace: NORMAL
          speechClarity: CLEAR
          hasDisfluencies: false
          baseEmotion: FRUSTRATED
          intentClarity: CLEAR
          confirmationStyle: EXPLICIT
          memoryReliability: HIGH
          responseTiming: NORMAL
          interruption: OCCASIONAL
          backstoryPrompt: A busy professional calling during lunch break
          idleMessages: null
          idleTimeoutSeconds: 10
          idleMessageMaxSpokenCount: 3
          idleMessageResetCountOnUserSpeechEnabled: true
          properties:
            age: '35'
            zipCode: '94105'
          createdAt: '2025-01-10T12:00:00.000Z'
          updatedAt: '2025-01-10T12:00:00.000Z'
        backgroundNoise:
          backgroundNoise: CITY
          backgroundNoiseVolume: 0.1
          source: ENVIRONMENT
        scenario:
          id: f8e7d6c5-b4a3-9281-7069-5f4e3d2c1b0a
          description: >-
            Patient calling to schedule an urgent dental appointment due to
            severe tooth pain
        agentEndpoint:
          id: 3c2b1a09-8f7e-6d5c-4b3a-291807060504
          name: PHONE
          phoneNumber: '+15555551234'
          type: PHONE
        createdAt: '2025-01-15T14:23:45.123Z'
        startedAt: '2025-01-15T14:24:15.456Z'
        completedAt: '2025-01-15T14:28:32.789Z'
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - validation
            - authentication
            - forbidden
            - not_found
            - conflict
            - payment_required
            - rate_limit
            - internal
          description: The error type category
          examples:
            - validation
            - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
            - invalid_parameter
            - missing_required_field
            - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
            - The request was invalid
            - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
            - email
            - user_id
        details:
          description: Additional error context information
      required:
        - type
        - code
        - message
    SimulationRunPlanRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Run plan ID
        name:
          type: string
          description: Run plan name
        variables:
          type: object
          additionalProperties:
            type: string
          description: >-
            Run-plan-level variables resolved for this job, keyed by variable
            name. Values are stringified by their declared type.
      required:
        - id
        - name
        - variables
    SimulationJobEnrichment:
      type: object
      properties:
        requested:
          type: boolean
          description: >-
            Whether the run plan asked for the customer's live conversation to
            be merged into this run.
        outcome:
          type: string
          enum:
            - NOT_REQUESTED
            - WAITING
            - MERGED
            - TIMED_OUT
            - SKIPPED
            - UNKNOWN
          description: >-
            How the wait for the live conversation resolved. `WAITING` means the
            run is holding open for it right now. `MERGED` means it arrived and
            live-sourced metrics were scored against it. `TIMED_OUT` and
            `SKIPPED` both mean it never arrived, so scoring fell back to the
            simulated side: read `metricsScoredOnSimulationInstead` and
            `metricsNotCollected` for what that cost. `UNKNOWN` is a run that
            finished before Roark started recording this.
        waitStartedAt:
          type:
            - string
            - 'null'
          description: >-
            When the run began holding open for the live conversation. Null if
            it never waited.
        waitEndedAt:
          type:
            - string
            - 'null'
          description: >-
            When the wait ended, however it ended. Null if it never waited or is
            still waiting.
        metricsScoredOnSimulationInstead:
          type:
            - integer
            - 'null'
          description: >-
            Metrics that asked for the live side and were scored against the
            simulated side because no live conversation arrived. Null on runs
            that predate this recording.
        metricsNotCollected:
          type:
            - integer
            - 'null'
          description: >-
            Metrics that only support the live side and so were not scored at
            all. Null on runs that predate this recording.
      required:
        - requested
        - outcome
      description: >-
        What happened to this run's live-conversation enrichment, and what
        scoring fell back to when none arrived.
    SimulationJobInvalidation:
      type: object
      properties:
        reason:
          type: string
          enum:
            - SCRIPT_DIVERGED
            - REQUIRED_STEP_NOT_REACHED
            - REQUIRED_STAGE_INCOMPLETE
            - CALLER_NEVER_TOOK_OVER
            - AGENT_NEVER_SPOKE
          description: >-
            Why the result does not count. `SCRIPT_DIVERGED`: a strict flow went
            off script at a step whose off-script policy is HANG_UP_INVALIDATE.
            `REQUIRED_STAGE_INCOMPLETE`: the call ended before it got through a
            stage its flow requires. `CALLER_NEVER_TOOK_OVER`: the call opened
            on the persona of a preceding flow, which never handed the phone to
            the persona under test, so none of that persona's properties were
            exercised. `AGENT_NEVER_SPOKE`: your agent answered and never said a
            word (it hung up within seconds, or the line stayed silent until our
            caller gave up), so there was nothing to grade.
        detail:
          type:
            - string
            - 'null'
          description: >-
            One sentence: where the script was left and what your agent did
            instead.
        invalidatedAt:
          type: string
          description: When the run was invalidated.
      required:
        - reason
        - invalidatedAt
      description: >-
        Present when the run was invalidated: the call ended before a step its
        flow requires for a valid run, or a strict flow went off script at a
        step whose policy invalidates the run. It keeps its transcript and
        recording, but nothing scored it and it is excluded from every run
        total.
    SimulationJobBackgroundNoise:
      type: object
      properties:
        backgroundNoise:
          type: string
          enum:
            - NONE
            - AIRPORT
            - CHILDREN_PLAYING
            - CITY
            - COFFEE_SHOP
            - CONSTRUCTION
            - CRYING_BABY
            - DRIVING
            - LIBRARY
            - OFFICE
            - THUNDERSTORM
            - TRAIN
          description: >-
            The noise bed the simulated caller was placed with. NONE when the
            call ran in silence.
        backgroundNoiseVolume:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Linear gain (0..1) the bed played at. 1 is as loud as the caller’s
            voice.
        source:
          type: string
          enum:
            - ENVIRONMENT
            - PERSONA
          description: >-
            `ENVIRONMENT` when the flow’s environment decided the bed (a sweep
            arm, or an environment with noise), `PERSONA` when the persona’s own
            setting did.
      required:
        - backgroundNoise
        - backgroundNoiseVolume
        - source
      description: >-
        The background noise the call actually ran with.
        `persona.backgroundNoise` is only what the persona was set to; a flow’s
        environment overrides it, and on a background-noise sweep every arm’s
        persona says NONE while the arms differ here. Filter by arm on this
        field.
    ScenarioResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Scenario ID
        description:
          type:
            - string
            - 'null'
          description: Scenario description
      required:
        - id
      description: Scenario used in a simulation
    AgentEndpointResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Agent endpoint ID
        name:
          type: string
          description: Agent endpoint name
        phoneNumber:
          type:
            - string
            - 'null'
          description: Agent endpoint phone number
        type:
          type: string
          enum:
            - PHONE
            - WEBSOCKET
            - LIVEKIT
            - SMALL_WEBRTC
            - ELEVENLABS_WS
            - KORE
            - GOOGLE_CES
            - DAILY
            - ROARK_WEBRTC
          description: Agent endpoint type
      required:
        - id
        - name
        - phoneNumber
        - type
      description: Agent endpoint used in a simulation
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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