> ## 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. # List simulations > List simulations with optional filtering and sorting. ## OpenAPI ````yaml /api-reference/v1/simulations-v1.yaml get /simulations 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: get: tags: - Simulations summary: List simulations description: List simulations with optional filtering and sorting. operationId: listSimulations parameters: - name: filter in: query required: false schema: type: string description: > Filter expression syntax. Supported fields: `status`, `agent_id`, `persona_id`, `test_set_id`, `test_case_id`, `run_id`, `external_conversation_id`, `mutation_id`, `mutation_name`, `create_time` Operators: `=`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR` Values may be unquoted or double-quoted. Values containing spaces must be quoted (e.g., `status="IN PROGRESS"`). The `external_conversation_id` field is your system's conversation ID for cross-system lookup. **Mutation Filtering:** Use `mutation_id` or `mutation_name` to filter simulations by agent mutation variant. Base agent simulations have both `mutation_id` and `mutation_name` = null. To get only base agent results, filter for simulations where `mutation_id` is not set. example: status=COMPLETED AND agent_id=gk3jK9mPq2xRt5vW8yZaBc - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 1000 default: 50 description: Maximum number of results per page example: 50 - name: page_token in: query required: false schema: type: string description: Opaque pagination token from previous response - name: order_by in: query required: false schema: type: string default: '-create_time' description: | Sort order specification. Format: `field` or `-field` (descending) Supported fields: `create_time`, `status` example: '-create_time' responses: '200': description: List of simulations content: application/json: schema: $ref: '#/components/schemas/ListSimulationsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: ListSimulationsResponse: type: object required: - simulations properties: simulations: type: array items: $ref: '#/components/schemas/SimulationResource' description: Array of simulation resources (summary view without results) next_page_token: type: string description: Token for fetching next page of results (if more exist) example: eyJvZmZzZXQiOiA1MH0= 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 ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorInfo' 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 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 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: BadRequest: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INVALID_ARGUMENT message: Request validation failed details: - field: iteration_count description: Value must be between 1 and 10 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 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. ````