> ## 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 runs > Retrieve a paginated list of simulation runs with optional filtering and sorting. ## OpenAPI ````yaml /api-reference/v1/runs-v1.yaml get /runs openapi: 3.0.3 info: title: Coval Runs API version: 1.0.0 description: | Launch and manage simulation runs 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: Runs description: Launch and manage simulation runs paths: /runs: get: tags: - Runs summary: List runs description: > Retrieve a paginated list of simulation runs with optional filtering and sorting. operationId: listRuns parameters: - name: filter in: query required: false schema: type: string description: > Filter expression syntax. Supported fields: `status`, `agent_id`, `persona_id`, `test_set_id`, `create_time`, `update_time`, `created_by`, `tag` Operators: `=`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR` Values may be unquoted or double-quoted. Values containing spaces must be quoted (e.g., `status="IN PROGRESS"`). examples: byStatus: value: status="COMPLETED" AND agent_id=gk3jK9mPq2xRt5vW8yZaBc summary: Filter by status and agent byTag: value: tag="regression" summary: Filter by tag - 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`, `update_time`, `status`, `agent_id`, `persona_id`, `test_set_id` example: '-create_time' responses: '200': description: List of runs content: application/json: schema: type: object required: - runs properties: runs: type: array items: $ref: '#/components/schemas/Run' next_page_token: type: string description: Token for fetching the next page of results example: eyJvZmZzZXQiOiA1MH0= '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: Run: type: object required: - name - run_id - status - create_time properties: name: type: string description: Resource name in format "runs/{run_id}" example: runs/abc123xyz789 run_id: type: string minLength: 22 maxLength: 22 description: Unique identifier for this simulation run example: 8EktrIgaVxn9LfxkIynagX display_name: type: string nullable: true description: >- Human-readable name for the run, set via `metadata.display_name` at launch. example: Nightly regression – checkout flow status: type: string enum: - PENDING - IN QUEUE - IN PROGRESS - COMPLETED - FAILED - CANCELLED - DELETED description: Current status of the simulation run example: COMPLETED create_time: type: string format: date-time description: Timestamp when the run was created (ISO 8601) example: '2025-10-14T12:00:00Z' update_time: type: string format: date-time description: Timestamp when the run was last updated (ISO 8601) example: '2025-10-14T12:15:00Z' agent_id: type: string nullable: true description: ID of the agent being tested example: gk3jK9mPq2xRt5vW8yZaBc persona_id: type: string nullable: true description: ID of the simulated persona used example: hL4kL0nQr3ySt6vX9zAcDd test_set_id: type: string nullable: true description: ID of the test set containing test cases example: aB1cD2eF tags: type: array items: type: string maxLength: 200 maxItems: 20 description: Tags for categorizing and filtering runs example: - regression - v2.1 progress: $ref: '#/components/schemas/Progress' results: $ref: '#/components/schemas/Results' metadata: type: object additionalProperties: true description: Custom metadata provided during launch example: campaign_id: q4_2025 environment: production error: type: string nullable: true description: Error message if status is FAILED example: Agent connection timeout Progress: type: object description: Progress information for the run required: - total_test_cases - completed_test_cases - failed_test_cases - in_progress_test_cases properties: total_test_cases: type: integer description: Total number of test cases example: 10 completed_test_cases: type: integer description: Number of completed test cases example: 8 failed_test_cases: type: integer description: Number of failed test cases example: 1 in_progress_test_cases: type: integer description: Number of test cases currently running example: 1 Results: type: object nullable: true description: Results summary (only for COMPLETED runs) required: - output_ids - metrics properties: output_ids: type: array items: type: string description: IDs of simulation outputs (test case results) example: - sim_output_abc123 - sim_output_def456 metrics: type: object additionalProperties: $ref: '#/components/schemas/MetricSummary' description: Aggregated metric results example: availability: mean: 0.95 min: 0.85 max: 1 Error: type: object required: - code - message properties: code: type: string enum: - INVALID_ARGUMENT - UNAUTHENTICATED - PERMISSION_DENIED - NOT_FOUND - INTERNAL description: Machine-readable error code example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: 'Invalid agent_id: Agent not found' details: type: array items: $ref: '#/components/schemas/ErrorDetail' MetricSummary: type: object description: Aggregated metric statistics required: - mean properties: mean: type: number format: float description: Mean value across all test cases example: 0.95 min: type: number format: float description: Minimum value example: 0.85 max: type: number format: float description: Maximum value example: 1 ErrorDetail: type: object 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 'gk3jK9mPq2xRt5vW8yZaBc' does not exist or is not accessible by your organization responses: BadRequest: description: Bad Request content: application/json: schema: type: object required: - error properties: error: $ref: '#/components/schemas/Error' example: error: code: INVALID_ARGUMENT message: Request validation failed details: - field: iteration_count description: Value must be between 1 and 10 Unauthorized: description: Unauthorized content: application/json: schema: type: object required: - error properties: error: $ref: '#/components/schemas/Error' example: error: code: UNAUTHENTICATED message: Invalid or missing API key details: - field: X-API-Key description: API key is required in the X-API-Key header InternalError: description: Internal Server Error content: application/json: schema: type: object required: - error properties: error: $ref: '#/components/schemas/Error' 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 ````