> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# Get Simulation Run Item

GET https://api.vapi.ai/eval/simulation/run/{id}/item/{itemId}

Returns the specified run item, including its evaluation results and the ID of the call that ran it.

Reference: https://docs.vapi.ai/api-reference/simulation-runs/simulation-run-controller-find-item

## Authentication

- `Authorization` header (bearer token, required) — Authenticate server-side requests with a private Vapi API key. Create or copy a key from the [Vapi Dashboard](https://dashboard.vapi.ai) and send it in the `Authorization` header as `Bearer <token>`. Keep private API keys out of client-side code and public repositories.

## Request

### Path parameters

- `id` (string, required) — The unique identifier of the simulation run.
- `itemId` (string, required) — The unique identifier of the run item.

## Response

### 200

- `id` (string, required) — This is the unique identifier for the simulation run item.
- `orgId` (string, required) — This is the unique identifier for the organization.
- `simulationId` (string, required) — This is the ID of the simulation this run belongs to.
- `status` (enum, required) — The run item's current status.
  - Allowed values: `queued`, `running`, `evaluating`, `passed`, `failed`, `canceled`
- `queuedAt` (datetime, required) — This is the ISO 8601 date-time string of when the run was queued.
- `createdAt` (datetime, required) — This is the ISO 8601 date-time string of when the run item was created.
- `updatedAt` (datetime, required) — This is the ISO 8601 date-time string of when the run item was last updated.
- `startedAt` (datetime, optional) — This is the ISO 8601 date-time string of when the run started.
- `completedAt` (datetime, optional) — This is the ISO 8601 date-time string of when the run completed.
- `failedAt` (datetime, optional) — This is the ISO 8601 date-time string of when the run failed.
- `canceledAt` (datetime, optional) — This is the ISO 8601 date-time string of when the run was canceled.
- `failureReason` (string, optional) — Why the run item failed, when applicable.
- `callId` (string, optional) — The ID of the call that ran this item.
- `runId` (string, optional) — This is the ID of the parent run (batch/group).
- `hooks` (list of SimulationRunItemHooksItems, optional) — Hooks configured for this simulation run item
- `iterationNumber` (double, optional, default: 1) — Which iteration of the simulation this item represents.
- `sessionId` (string, optional) — This is the session ID for chat-based simulations (webchat transport).
- `scenarioId` (string, optional) — The ID of the scenario used for this run item.
- `personalityId` (string, optional) — The ID of the personality used for this run item.
- `metadata` (SimulationRunItemMetadata, optional) — This is the metadata containing snapshots and call data.
- `results` (SimulationRunItemResults, optional) — The evaluation results for this run item.
- `improvementSuggestions` (SimulationRunItemImprovements, optional) — AI-generated suggestions for improving the assistant or squad's system prompt, tools, and scenarios after a failed run.
- `configurations` (SimulationRunConfiguration, optional) — This is the configuration for how this simulation run executes.

## Types

### SimulationRunItemHooksItems

### SimulationRunItemMetadata

- `assistant` (map from string to any, optional) — This is a snapshot of the assistant at run creation time.
- `squad` (map from string to any, optional) — This is a snapshot of the squad at run creation time.
- `scenario` (map from string to any, optional) — This is a snapshot of the scenario at run creation time.
- `personality` (map from string to any, optional) — This is a snapshot of the personality at run creation time.
- `simulation` (map from string to any, optional) — This is a snapshot of the simulation at run creation time.
- `call` (SimulationRunItemCallMetadata, optional) — This is the call-related data (transcript, messages, recording).
- `hooks` (map from string to any, optional) — Hook execution state for this run item (used for idempotency + debugging).

### SimulationRunItemResults

- `evaluations` (list of StructuredOutputEvaluationResult, required) — This is the list of results from structured output evaluations.
- `passed` (boolean, required) — This indicates whether all required, non-skipped structured output evaluations and latency expectations passed.
- `latencyMetrics` (LatencyMetrics, optional) — This contains the latency metrics collected from the call.
- `latencyEvaluations` (list of LatencyEvaluationResult, optional) — This is the list of results from the scenario's latency expectations. Absent when the scenario has no latency expectations.

### SimulationRunItemImprovements

- `analysis` (string, required) — This is a summary analysis of why evaluations failed.
- `systemPromptSuggestions` (list of SimulationRunItemImprovementSuggestion, required) — This is the list of suggestions for improving the system prompt.
- `toolSuggestions` (list of SimulationRunItemImprovementSuggestion, required) — This is the list of suggestions for improving tools.
- `scenarioSuggestions` (list of SimulationRunItemImprovementSuggestion, required) — This is the list of suggestions for improving the scenario/evaluation plan.
- `suggestedSystemPrompt` (string, optional) — This is a complete revised system prompt if major changes are needed.

### SimulationRunConfiguration

- `transport` (SimulationRunTransportConfiguration, optional) — Transport configuration for the simulation run

### SimulationHookCallStarted

- `on` (enum, required)
  - Allowed values: `simulation.run.started`
- `do` (list of SimulationHookCallStartedDoItems, required)

### SimulationHookCallEnded

- `on` (enum, required)
  - Allowed values: `simulation.run.ended`
- `do` (list of SimulationHookCallEndedDoItems, required)

### SimulationRunItemCallMetadata

- `transcript` (string, optional) — This is the transcript of the conversation.
- `messages` (list of SimulationRunItemCallMetadataMessagesItems, optional) — This is the list of conversation messages in OpenAI format.
- `recordingUrl` (string, optional) — This is the URL to the call recording.
- `monitor` (SimulationRunItemCallMonitor, optional) — This is the call monitoring data (live listen URL).

### StructuredOutputEvaluationResult

- `structuredOutputId` (string, required) — This is the ID of the structured output that was evaluated. Will be 'inline' for inline structured output definitions.
- `name` (string, required) — This is the name of the structured output.
- `extractedValue` (StructuredOutputEvaluationResultExtractedValue, required, nullable) — This is the value extracted from the call by the structured output.
- `expectedValue` (StructuredOutputEvaluationResultExpectedValue, required) — This is the expected value that was defined in the evaluation plan.
- `comparator` (enum, required) — This is the comparison operator used for evaluation.
  - Allowed values: `=`, `!=`, `>`, `<`, `>=`, `<=`
- `passed` (boolean, required) — This indicates whether the evaluation passed (extracted value matched expected value using comparator).
- `required` (boolean, required) — This indicates whether this evaluation was required for the simulation to pass.
- `path` (string, optional) — This is the optional dot-notation path evaluated within an object structured output.
- `description` (string, optional) — This is the structured output description captured when the evaluation ran.
- `schema` (JsonSchema, optional) — This is the structured output schema captured when the evaluation ran.
- `error` (string, optional) — This contains any error that occurred during extraction.
- `isSkipped` (boolean, optional) — This indicates whether this evaluation was skipped (e.g., multimodal in chat mode).
- `skipReason` (string, optional) — This contains the reason for skipping the evaluation.

### LatencyMetrics

- `turnCount` (double, required) — This is the number of conversation turns.
- `avgTurn` (double, optional) — This is the average total turn latency in milliseconds.
- `avgTranscriber` (double, optional) — This is the average transcriber latency in milliseconds.
- `avgModel` (double, optional) — This is the average LLM/model latency in milliseconds.
- `avgVoice` (double, optional) — This is the average voice/TTS latency in milliseconds.
- `avgEndpointing` (double, optional) — This is the average endpointing latency in milliseconds.

### LatencyEvaluationResult

- `metric` (enum, required) — This is the latency component that was measured.
  - Allowed values: `turn`, `model`, `voice`
- `aggregation` (enum, required) — This is how the per-turn latencies were aggregated.
  - Allowed values: `mean`, `median`, `p95`, `max`
- `thresholdMs` (double, required) — This is the ceiling in milliseconds the aggregated latency was compared against.
- `sampleCount` (double, required) — This is the number of turns that contributed a value for this metric.
- `passed` (boolean, required) — This indicates whether the aggregated latency was at or below the threshold.
- `required` (boolean, required) — This indicates whether this expectation was required for the simulation to pass.
- `actualMs` (double, optional) — This is the aggregated latency in milliseconds, rounded to the nearest millisecond. The pass/fail verdict is decided on this rounded value. Absent when the expectation was skipped or no turn measured this metric.
- `isSkipped` (boolean, optional) — This indicates whether this expectation was skipped. Expectations are only skipped on chat simulations and GPT Live targets, which record no latency.
- `skipReason` (string, optional) — This contains the reason for skipping the expectation.

### SimulationRunItemImprovementSuggestion

- `issue` (string, required) — This is the issue identified.
- `suggestion` (string, required) — This is the suggested improvement.

### SimulationRunTransportConfiguration

- `provider` (enum, required) — Transport provider for the simulation run
  - Allowed values: `vapi.websocket`, `vapi.webchat`

### SimulationHookCallStartedDoItems

### SimulationHookCallEndedDoItems

### SimulationRunItemCallMetadataMessagesItems

### SimulationRunItemCallMonitor

- `listenUrl` (string, optional) — This is the WebSocket URL to listen to the live call audio (combined both parties).

### StructuredOutputEvaluationResultExtractedValue

This is the value extracted from the call by the structured output.

### StructuredOutputEvaluationResultExpectedValue

This is the expected value that was defined in the evaluation plan.

### JsonSchema

JSON Schema definition used to describe structured data for extraction, validation, or model output.

- `type` (enum, required) — This is the type of output you'd like. `string`, `number`, `integer`, `boolean` are the primitive types and should be obvious. `array` and `object` are more interesting and quite powerful. They allow you to define nested structures. For `array`, you can define the schema of the items in the array using the `items` property. For `object`, you can define the properties of the object using the `properties` property.
  - Allowed values: `string`, `number`, `integer`, `boolean`, `array`, `object`
- `items` (JsonSchema, optional) — This is required if the type is "array". This is the schema of the items in the array. This is a recursive reference to JsonSchema.
- `properties` (map from string to JsonSchema, optional) — This is required if the type is "object". This specifies the properties of the object. This is a map of property names to JsonSchema objects.
- `description` (string, optional) — This is the description to help the model understand what it needs to output.
- `pattern` (string, optional) — This is the pattern of the string. This is a regex that will be used to validate the data in question. To use a common format, use the `format` property instead. OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs#supported-properties
- `format` (enum, optional) — This is the format of the string. To pass a regex, use the `pattern` property instead. OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=string-restrictions
  - Allowed values: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uuid`
- `required` (list of string, optional) — This is a list of properties that are required. This only makes sense if the type is "object".
- `enum` (list of string, optional) — This array specifies the allowed values that can be used to restrict the output of the model.
- `title` (string, optional) — This is the title of the schema.

### SimulationHookWebhookAction

- `type` (enum, required)
  - Allowed values: `webhook`
- `server` (Server, optional) — Optional server override for this hook action. If omitted, runtime defaults may apply (e.g. org server).
- `include` (SimulationHookInclude, optional) — Optional payload include controls.

### Server

Configuration for requests Vapi sends to a customer server, including URL, authentication, headers, timeout, encryption, static IP addresses, and retry behavior.

- `timeoutSeconds` (double, optional) — This is the timeout in seconds for the request. Defaults to 20 seconds. @default 20
- `credentialId` (string, optional) — The credential ID for server authentication
- `staticIpAddressesEnabled` (boolean, optional) — If enabled, requests will originate from a static set of IPs owned and managed by Vapi. @default false
- `encryptedPaths` (list of string, optional) — This is the paths to encrypt in the request body if credentialId and encryptionPlan are defined.
- `url` (string, optional) — This is where the request will be sent.
- `headers` (ServerHeaders, optional) — These are the headers to include in the request. Each key-value pair represents a header name and its value. Note: Specifying an Authorization header here will override the authorization provided by the `credentialId` (if provided). This is an anti-pattern and should be avoided outside of edge case scenarios.
- `backoffPlan` (BackoffPlan, optional) — This is the backoff plan if the request fails. Defaults to undefined (the request will not be retried). @default undefined (the request will not be retried)

### SimulationHookInclude

- `transcript` (boolean, optional, default: false) — Include transcript in the hook payload
- `messages` (boolean, optional, default: false) — Include messages in the hook payload
- `recordingUrl` (boolean, optional, default: false) — Include recordingUrl in the hook payload

### ServerHeaders

These are the headers to include in the request. Each key-value pair represents a header name and its value. Note: Specifying an Authorization header here will override the authorization provided by the `credentialId` (if provided). This is an anti-pattern and should be avoided outside of edge case scenarios.

### BackoffPlan

Controls retry behavior for failed server requests, including strategy, maximum retries, base delay, and status codes excluded from retries.

- `type` (enum, required) — This is the type of backoff plan to use. Defaults to fixed. @default fixed
  - Allowed values: `fixed`, `exponential`
- `maxRetries` (double, required) — This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries). @default 0
- `baseDelaySeconds` (double, required) — Base delay in seconds. For fixed backoff, this is the delay between retries. For exponential backoff, this is the initial delay.
- `excludedStatusCodes` (list of BackoffPlanExcludedStatusCodesItems, optional) — HTTP status codes that should not trigger a retry. By default, any non-2xx status code not listed here can be retried.

### BackoffPlanExcludedStatusCodesItems

## Examples

**Response**

```json
{
  "id": "string",
  "orgId": "string",
  "simulationId": "string",
  "status": "queued",
  "queuedAt": "2024-01-15T09:30:00Z",
  "createdAt": "2024-01-15T09:30:00Z",
  "updatedAt": "2024-01-15T09:30:00Z",
  "startedAt": "2024-01-15T09:30:00Z",
  "completedAt": "2024-01-15T09:30:00Z",
  "failedAt": "2024-01-15T09:30:00Z",
  "canceledAt": "2024-01-15T09:30:00Z",
  "failureReason": "string",
  "callId": "string",
  "runId": "string",
  "hooks": [
    {
      "do": [
        {
          "include": {
            "messages": false,
            "recordingUrl": false,
            "transcript": false
          },
          "server": {
            "backoffPlan": {
              "baseDelaySeconds": 1,
              "excludedStatusCodes": [
                400,
                401,
                403,
                404
              ],
              "maxRetries": 0,
              "type": "fixed"
            },
            "credentialId": "550e8400-e29b-41d4-a716-446655440000",
            "encryptedPaths": [
              "string"
            ],
            "headers": {},
            "staticIpAddressesEnabled": false,
            "timeoutSeconds": 20,
            "url": "string"
          },
          "type": "webhook"
        }
      ],
      "on": "simulation.run.started"
    }
  ],
  "iterationNumber": 1,
  "sessionId": "string",
  "scenarioId": "string",
  "personalityId": "string",
  "metadata": {
    "assistant": {},
    "squad": {},
    "scenario": {},
    "personality": {},
    "simulation": {},
    "call": {
      "transcript": "string",
      "messages": [
        {}
      ],
      "recordingUrl": "string",
      "monitor": {
        "listenUrl": "string"
      }
    },
    "hooks": {}
  },
  "results": {
    "evaluations": [
      {
        "structuredOutputId": "string",
        "name": "string",
        "extractedValue": 1.1,
        "expectedValue": 1.1,
        "comparator": "=",
        "passed": true,
        "required": true,
        "path": "string",
        "description": "string",
        "schema": {
          "type": "string",
          "items": {
            "type": "string",
            "items": {
              "type": "string",
              "items": {
                "type": "string",
                "items": {
                  "type": "string",
                  "items": {
                    "type": "string",
                    "items": {
                      "type": "string",
                      "items": {
                        "type": "string",
                        "items": {
                          "type": "string",
                          "items": {
                            "type": {},
                            "items": {},
                            "properties": {},
                            "description": {},
                            "pattern": {},
                            "format": {},
                            "required": {},
                            "enum": {},
                            "title": {}
                          },
                          "properties": {},
                          "description": "string",
                          "pattern": "string",
                          "format": "date-time",
                          "required": [
                            "string"
                          ],
                          "enum": [
                            "string"
                          ],
                          "title": "string"
                        },
                        "properties": {},
                        "description": "string",
                        "pattern": "string",
                        "format": "date-time",
                        "required": [
                          "string"
                        ],
                        "enum": [
                          "string"
                        ],
                        "title": "string"
                      },
                      "properties": {},
                      "description": "string",
                      "pattern": "string",
                      "format": "date-time",
                      "required": [
                        "string"
                      ],
                      "enum": [
                        "string"
                      ],
                      "title": "string"
                    },
                    "properties": {},
                    "description": "string",
                    "pattern": "string",
                    "format": "date-time",
                    "required": [
                      "string"
                    ],
                    "enum": [
                      "string"
                    ],
                    "title": "string"
                  },
                  "properties": {},
                  "description": "string",
                  "pattern": "string",
                  "format": "date-time",
                  "required": [
                    "string"
                  ],
                  "enum": [
                    "string"
                  ],
                  "title": "string"
                },
                "properties": {},
                "description": "string",
                "pattern": "string",
                "format": "date-time",
                "required": [
                  "string"
                ],
                "enum": [
                  "string"
                ],
                "title": "string"
              },
              "properties": {},
              "description": "string",
              "pattern": "string",
              "format": "date-time",
              "required": [
                "string"
              ],
              "enum": [
                "string"
              ],
              "title": "string"
            },
            "properties": {},
            "description": "string",
            "pattern": "string",
            "format": "date-time",
            "required": [
              "string"
            ],
            "enum": [
              "string"
            ],
            "title": "string"
          },
          "properties": {},
          "description": "string",
          "pattern": "string",
          "format": "date-time",
          "required": [
            "string"
          ],
          "enum": [
            "string"
          ],
          "title": "string"
        },
        "error": "string",
        "isSkipped": true,
        "skipReason": "string"
      }
    ],
    "passed": true,
    "latencyMetrics": {
      "turnCount": 1.1,
      "avgTurn": 1.1,
      "avgTranscriber": 1.1,
      "avgModel": 1.1,
      "avgVoice": 1.1,
      "avgEndpointing": 1.1
    },
    "latencyEvaluations": [
      {
        "metric": "turn",
        "aggregation": "mean",
        "thresholdMs": 1.1,
        "sampleCount": 1.1,
        "passed": true,
        "required": true,
        "actualMs": 1.1,
        "isSkipped": true,
        "skipReason": "string"
      }
    ]
  },
  "improvementSuggestions": {
    "analysis": "string",
    "systemPromptSuggestions": [
      {
        "issue": "string",
        "suggestion": "string"
      }
    ],
    "toolSuggestions": [
      {
        "issue": "string",
        "suggestion": "string"
      }
    ],
    "scenarioSuggestions": [
      {
        "issue": "string",
        "suggestion": "string"
      }
    ],
    "suggestedSystemPrompt": "string"
  },
  "configurations": {
    "transport": {
      "provider": "vapi.websocket"
    }
  }
}
```