---
title: "Get simulation run by ID"
method: GET
path: "/simulations/{simulationReference}/batches/{simulationRunBatchReference}/runs/{simulationRunReference}"
tags: ["Simulation Runs"]
---

# Get simulation run by ID

`GET /simulations/{simulationReference}/batches/{simulationRunBatchReference}/runs/{simulationRunReference}`

Retrieve a specific simulation run by its reference ID.

## Path parameters

- `simulationReference` string, required
- `simulationRunBatchReference` string, required
- `simulationRunReference` string, required

## Query parameters

- `projectId` string, required

## Response `200`

Simulation run retrieved successfully

- object
  - `id` string, required — Unique identifier for the simulation run
  - `organisationReference` string, required — Organization reference
  - `projectReference` string, required — Project reference
  - `simulationReference` string, required — Reference ID of the simulated scenario
  - `simulationRunBatchReference` string, required — Reference ID of the simulation
  - `sequence` integer, required — Sequence number of this run in the simulation
  - `largeLanguageModelReferenceId` string, required — LLM reference ID used for this run
  - `endPointType` string — Endpoint type used for execution
  - `turns` object[], required — Array of conversation turns
    - `id` string — Turn identifier
    - `sequence` integer — Turn sequence number
    - `text` string — Turn text content
    - `data` object — Turn metadata and additional data
    - `createdAt` integer — Turn creation timestamp
  - `totalTurns` integer, required — Total number of turns in this run
  - `maxTurns` integer — Maximum allowed turns
  - `successCriteria` object[], required — Success criteria for this run
    - `type` string, required — Success criterion type
    - `params` object, required — Success criterion parameters
  - `metrics` object, required — Metrics and results of the simulation run
    - `sentiment` 'positive' | 'negative' | 'neutral', required — Sentiment analysis result
    - `success` boolean, required — Whether the run was successful
    - `results` object[] — Success criteria evaluation results
    - `successRate` object — Success rate calculation
      - `percentage` number, float
      - `numerator` integer
      - `denominator` integer
    - `summary` string — Summary of the simulation run
    - `isBatchStopped` boolean — Whether the simulation was stopped
    - `isConversationEnded` boolean — Whether the conversation ended naturally
    - `errorInfo` object — Error information if run failed
      - `category` 'NONE' | 'LLM_PROVIDER_ERROR' | 'AI_AGENT_TIMEOUT' | 'AI_AGENT_ERROR' | 'UNKNOWN' — Error category
      - `message` string — User-friendly error message
      - `technicalDetails` string — Technical error details
    - `status` 'SUCCESS' | 'FAILED' | 'ERROR' — Overall status of the run
  - `createdAt` integer, required — Creation timestamp
  - `createdBy` string, required — User who created this run
  - `duration` integer — Duration of the run in milliseconds
  - `expiresAt` string, date-time — Expiration timestamp

## Other responses

- `400` — Bad Request - Invalid input parameters
- `401` — Unauthorized - Invalid or missing authentication
- `403` — Forbidden - Insufficient permissions
- `404` — Not Found - Simulation run not found
- `500` — Internal Server Error - Server error

---

[API](https://skmtc.net/cognigy/apis/simulator-openapi-rest-ful-api-reference.md) · [All operations](https://skmtc.net/cognigy/apis/simulator-openapi-rest-ful-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cognigy/simulator-openapi-rest-ful-api-reference/revisions/85b2872bdfb7/schema)