> ## 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. # Update run > Replace the tag set for an existing simulation run. Provide an empty list to clear all tags. ## OpenAPI ````yaml /api-reference/v1/runs-v1.yaml patch /runs/{run_id} 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/{run_id}: patch: tags: - Runs summary: Update run description: | Replace the tag set for an existing simulation run. Provide an empty list to clear all tags. operationId: updateRun parameters: - name: run_id in: path required: true schema: type: string minLength: 22 maxLength: 22 description: Unique identifier for the run example: 7DjsqHfZUwm8KewjHxmZgW requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateRunRequest' examples: markBaseline: summary: Mark a run as a baseline value: tags: - baseline - production clearTags: summary: Clear all run tags value: tags: [] responses: '200': description: Run updated successfully content: application/json: schema: type: object required: - run properties: run: $ref: '#/components/schemas/Run' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: UpdateRunRequest: type: object required: - tags properties: tags: type: array items: type: string maxLength: 200 maxItems: 20 description: | Full replacement list of run tags. Duplicate tags are automatically removed. Leading/trailing whitespace is stripped. Provide an empty list to clear all tags. example: - baseline - production 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 Forbidden: description: Forbidden content: application/json: schema: type: object required: - error properties: error: $ref: '#/components/schemas/Error' example: error: code: PERMISSION_DENIED message: Access denied details: - description: Your organization does not have access to this resource NotFound: description: Not Found content: application/json: schema: type: object required: - error properties: error: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Run not found details: - field: run_id description: >- Run 'abc123xyz789' does not exist or is not accessible by your organization 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 ````