> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt > Use this file to discover all available pages before exploring further. # Get simulation runs by simulation > Retrieve all simulation runs for a specific simulation. ## OpenAPI ````yaml https://api-trial.cognigy.ai/testing/openapi/openapi-viewer.json get /simulations/{simulationReference}/batches/{simulationRunBatchReference}/runs openapi: 3.0.0 info: title: SIMULATOR OPENAPI REST-ful-API Reference version: 2025.20.0 description: > ### Introduction This is the [OpenAPI 3.0](https://swagger.io/specification/) documentation of the [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)-ful SIMULATOR OPENAPI API. ### Cross-Origin Resource Sharing This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with [W3C spec](https://www.w3.org/TR/cors/), which allows cross-domain communication from the browser. All responses have a wildcard same-origin header which makes the API completely accessible. ### Authentication SIMULATOR OPENAPI offers following forms of authentication: - Bearer Token (JWT) - API Key ### Error Handling This API uses HTTP status codes equal or above 400 to indicate errors. Error details are generated in compliance with [RFC 7807 - "Problem Details for HTTP APIs"](https://tools.ietf.org/html/rfc7807). Every error response contains a traceId, which should be provided to the SIMULATOR OPENAPI Technical Support when reporting an error. contact: name: Cognigy Technical Support url: https://www.cognigy.com email: support@cognigy.com license: name: Cognigy Proprietary License servers: - url: https://api-trial.cognigy.ai/testing description: Cognigy Service Testing API security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: Simulations description: >- Simulation management operations - Create, read, update, and delete simulations externalDocs: description: SIMULATOR OPENAPI Documentation url: https://docs.cognigy.com/docs/service-testing/ paths: /simulations/{simulationReference}/batches/{simulationRunBatchReference}/runs: get: tags: - Simulation Runs summary: Get simulation runs by simulation description: Retrieve all simulation runs for a specific simulation. operationId: getSimulationRunsByBatch parameters: - name: projectId in: query required: true schema: type: string description: Project identifier - in: path name: simulationReference required: true schema: type: string description: Reference ID of the scenario - in: path name: simulationRunBatchReference required: true schema: type: string description: Reference ID of the simulation - name: filter in: query required: false schema: type: string description: Filter criteria for searching simulations - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Number of items to return per page - name: skip in: query required: false schema: type: integer minimum: 0 default: 0 description: Number of items to skip - name: sort in: query required: false schema: type: string description: Sort order (e.g., 'name:asc', 'createdAt:desc') - in: query name: next schema: type: string description: Pagination cursor for next page - in: query name: previous schema: type: string description: Pagination cursor for previous page - in: query name: endPointType schema: type: string description: Filter by endpoint type responses: '200': description: List of simulation runs retrieved successfully content: application/json: schema: type: object properties: data: type: array description: Array of simulation run objects items: type: object properties: id: type: string description: Unique identifier for the simulation run organisationReference: type: string description: Organization reference projectReference: type: string description: Project reference simulationReference: type: string description: Reference ID of the simulated scenario simulationRunBatchReference: type: string description: Reference ID of the simulation sequence: type: integer description: Sequence number of this run in the simulation largeLanguageModelReferenceId: type: string description: LLM reference ID used for this run endPointType: type: string description: Endpoint type used for execution turns: type: array description: Array of conversation turns items: type: object properties: id: type: string description: Turn identifier sequence: type: integer description: Turn sequence number text: type: string description: Turn text content data: type: object description: Turn metadata and additional data createdAt: type: integer format: int64 description: Turn creation timestamp totalTurns: type: integer description: Total number of turns in this run maxTurns: type: integer description: Maximum allowed turns successCriteria: type: array description: Success criteria for this run items: type: object properties: type: type: string description: Success criterion type params: type: object description: Success criterion parameters required: - type - params metrics: type: object description: Metrics and results of the simulation run properties: sentiment: type: string enum: - positive - negative - neutral description: Sentiment analysis result success: type: boolean description: Whether the run was successful results: type: array description: Success criteria evaluation results items: type: object successRate: type: object description: Success rate calculation properties: percentage: type: number format: float numerator: type: integer denominator: type: integer summary: type: string description: Summary of the simulation run isBatchStopped: type: boolean description: Whether the simulation was stopped isConversationEnded: type: boolean description: Whether the conversation ended naturally errorInfo: type: object description: Error information if run failed properties: category: type: string enum: - NONE - LLM_PROVIDER_ERROR - AI_AGENT_TIMEOUT - AI_AGENT_ERROR - UNKNOWN description: Error category message: type: string description: User-friendly error message technicalDetails: type: string description: Technical error details status: type: string enum: - SUCCESS - FAILED - ERROR description: Overall status of the run createdAt: type: integer format: int64 description: Creation timestamp createdBy: type: string description: User who created this run duration: type: integer description: Duration of the run in milliseconds expiresAt: type: string format: date-time description: Expiration timestamp required: - id - organisationReference - projectReference - simulationReference - simulationRunBatchReference - sequence - largeLanguageModelReferenceId - turns - totalTurns - successCriteria - metrics - createdAt - createdBy pagination: type: object properties: limit: type: integer description: Number of items per page skip: type: integer description: Number of items skipped total: type: integer description: Total number of items hasNext: type: boolean description: Whether there are more items hasPrevious: type: boolean description: Whether there are previous items next: type: string nullable: true description: Cursor for next page previous: type: string nullable: true description: Cursor for previous page required: - limit - skip - total - hasNext - hasPrevious '400': description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: error: type: string description: Validation error message field: type: string description: Field that failed validation code: type: string description: Validation error code traceId: type: string description: Trace ID for debugging required: - error - field '401': description: Unauthorized - Invalid or missing authentication content: application/json: schema: type: object properties: error: type: string description: Unauthorized error message code: type: string description: Unauthorized error code traceId: type: string description: Trace ID for debugging required: - error '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Forbidden error message code: type: string description: Forbidden error code traceId: type: string description: Trace ID for debugging required: - error '500': description: Internal Server Error - Server error content: application/json: schema: type: object properties: error: type: string description: Error message code: type: string description: Error code traceId: type: string description: Trace ID for debugging required: - error security: - bearerAuth: [] - apiKeyAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT Bearer Token for authentication apiKeyAuth: type: apiKey in: header name: X-API-Key description: API Key for authentication ````