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

# Get simulation runs by simulation

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

Retrieve all simulation runs for a specific simulation.

## Path parameters

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

## Query parameters

- `projectId` string, required
- `filter` string
- `limit` integer
- `skip` integer
- `sort` string
- `next` string
- `previous` string
- `endPointType` string

## Response `200`

List of simulation runs retrieved successfully

- object
  - `data` object[] — Array of simulation run objects
    - `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' — Sentiment analysis result
      - `success` boolean — 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
  - `pagination` object
    - `limit` integer, required — Number of items per page
    - `skip` integer, required — Number of items skipped
    - `total` integer, required — Total number of items
    - `hasNext` boolean, required — Whether there are more items
    - `hasPrevious` boolean, required — Whether there are previous items
    - `next` string, nullable — Cursor for next page
    - `previous` string, nullable — Cursor for previous page

## Other responses

- `400` — Bad Request - Invalid input parameters
- `401` — Unauthorized - Invalid or missing authentication
- `403` — Forbidden - Insufficient permissions
- `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)