> ## Documentation Index > Fetch the complete documentation index at: https://docs.coval.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get simulation > Get a simulation by ID. ## OpenAPI ````yaml /api-reference/v1/simulations-v1.yaml get /simulations/{simulation_id} openapi: 3.0.3 info: title: Coval Simulations API version: 1.0.0 description: | Launch and manage voice simulations for AI agent testing. contact: name: Coval API Support email: support@coval.dev url: https://docs.coval.ai license: name: Proprietary url: https://coval.dev/terms servers: - url: https://api.coval.dev/v1 description: Production API security: - ApiKeyAuth: [] tags: - name: Simulations description: Launch and manage individual simulation executions - name: Metric Outputs description: Retrieve metric computation results for simulations paths: /simulations/{simulation_id}: get: tags: - Simulations summary: Get simulation description: Get a simulation by ID. operationId: getSimulation parameters: - name: simulation_id in: path required: true schema: type: string minLength: 22 maxLength: 27 description: The simulation ID example: 3zfmuDbVQsi4GaseDtiVcS responses: '200': description: Simulation resource content: application/json: schema: $ref: '#/components/schemas/GetSimulationResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: GetSimulationResponse: type: object required: - simulation properties: simulation: $ref: '#/components/schemas/SimulationResourceFull' SimulationResourceFull: allOf: - $ref: '#/components/schemas/SimulationResource' - type: object properties: transcript: type: array items: $ref: '#/components/schemas/TranscriptMessage' nullable: true description: Full conversation transcript (only included in GET, not LIST) ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorInfo' SimulationResource: type: object required: - name - simulation_id - run_id - status - create_time - has_audio properties: name: type: string description: Resource name in format "simulations/{simulation_id}" example: simulations/abc123xyz789 simulation_id: type: string description: The unique identifier for this simulation execution example: abc123xyz789 run_id: type: string description: The parent run ID (for grouping simulations) example: abc123xyz789 status: type: string enum: - PENDING - IN QUEUE - IN PROGRESS - COMPLETED - FAILED - CANCELLED - DELETED description: Current status of the simulation example: COMPLETED create_time: type: string format: date-time description: Timestamp when the simulation was created (ISO 8601, UTC) example: '2025-10-14T12:00:00Z' agent_id: type: string nullable: true description: Reference to agent resource example: gk3jK9mPq2xRt5vW8yZaBc persona_id: type: string nullable: true description: Reference to persona resource example: hL4kL0nQr3ySt6vX9zAcDd test_set_id: type: string nullable: true description: Reference to test set resource example: aB1cD2eF test_case_id: type: string nullable: true description: Reference to test case that was executed example: test_xyz123 has_audio: type: boolean description: Whether audio recording is available for this simulation example: true source: description: >- The caller/initiating side of the simulation (the persona); null when not addressable type: object nullable: true oneOf: - $ref: '#/components/schemas/PhoneEndpoint' - $ref: '#/components/schemas/SipEndpoint' - $ref: '#/components/schemas/WebsocketEndpoint' discriminator: propertyName: type destination: description: The agent side of the simulation; null when not addressable type: object nullable: true oneOf: - $ref: '#/components/schemas/PhoneEndpoint' - $ref: '#/components/schemas/SipEndpoint' - $ref: '#/components/schemas/WebsocketEndpoint' discriminator: propertyName: type error_message: type: string nullable: true description: Error message if simulation failed or was cancelled example: Simulation failed to run. mutation_id: type: string nullable: true description: ID of the mutation variant used, or null for base agent simulations. example: 01ARZ3NDEKTSV4RRFFQ69G5FAV mutation_name: type: string nullable: true description: >- Display name of the mutation variant, or null for base agent simulations. example: GPT-4 Fast VAD notes: type: string nullable: true description: >- Free-text notes attached to the simulation. Settable via PATCH /simulations/{simulation_id}. example: Reviewed – false positive is_public: type: boolean description: >- Whether the simulation is shared via a public link. Settable via PATCH /simulations/{simulation_id}. example: false TranscriptMessage: type: object required: - role - content properties: role: type: string description: Message role (user, assistant, system) example: assistant content: description: Message content (can be string or structured object) oneOf: - type: string - type: object example: Hello! How can I help you today? start_timestamp: type: string description: Start timestamp in seconds example: '0.0' end_timestamp: type: string description: End timestamp in seconds example: '2.5' start_offset: type: integer description: Start offset in milliseconds example: 0 end_offset: type: integer description: End offset in milliseconds example: 2500 ErrorInfo: type: object required: - code - message properties: code: type: string enum: - INVALID_ARGUMENT - UNAUTHENTICATED - PERMISSION_DENIED - NOT_FOUND - FAILED_PRECONDITION - INTERNAL description: Machine-readable error code example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Request validation failed details: type: array items: $ref: '#/components/schemas/ErrorDetail' description: Detailed information about specific error fields PhoneEndpoint: type: object required: - type - value properties: type: type: string enum: - phone description: Endpoint kind discriminator value: type: string description: Phone number in E.164 format example: '+15551234567' SipEndpoint: type: object required: - type - value properties: type: type: string enum: - sip description: Endpoint kind discriminator value: type: string description: SIP URI example: sip:agent@voip.example.com WebsocketEndpoint: type: object required: - type - value properties: type: type: string enum: - websocket description: Endpoint kind discriminator value: type: string description: WebSocket URL example: wss://agent.example.com/stream ErrorDetail: type: object required: - description properties: field: type: string description: The field that caused the error (if applicable) example: agent_id description: type: string description: Human-readable description of the error example: Agent not found or not accessible by your organization responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Missing API Key details: - field: X-API-Key description: X-API-Key header is required NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Agent not found details: - field: agent_id description: Agent 'gk3jK9mPq2xRt5vW8yZaBc' does not exist InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Internal server error details: - description: An unexpected error occurred. Please contact support. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: | API key for authentication. ````