> ## 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 report > Partially update a saved report. To group by metadata, provide both `compare_by: metadata` and `metadata_key`. ## OpenAPI ````yaml /api-reference/v1/reports-v1.yaml patch /reports/{report_id} openapi: 3.0.3 info: title: Coval Reports API version: 1.0.0 description: | Create and manage saved multi-run reports from existing simulation runs. contact: name: Coval API Support email: support@coval.dev url: https://docs.coval.dev license: name: Proprietary url: https://coval.dev/terms servers: - url: https://api.coval.dev/v1 description: Production API security: - ApiKeyAuth: [] tags: - name: Reports description: CRUD operations for saved multi-run reports paths: /reports/{report_id}: patch: tags: - Reports summary: Update report description: | Partially update a saved report. To group by metadata, provide both `compare_by: metadata` and `metadata_key`. operationId: updateReport parameters: - $ref: '#/components/parameters/ReportId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateReportRequest' examples: rename: summary: Rename a report value: name: Q2 plan comparison metadataGrouping: summary: Update metadata grouping and visibility value: compare_by: metadata metadata_key: customer.plan permissions: PUBLIC responses: '200': description: Report updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateReportResponse' examples: updated: $ref: '#/components/examples/ReportCreated' '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' '503': $ref: '#/components/responses/ServiceUnavailable' security: - ApiKeyAuth: [] components: parameters: ReportId: name: report_id in: path required: true schema: type: string minLength: 26 maxLength: 26 description: Saved report ULID. example: 01JABCDEFGHJKMNPQRSTVWXYZ0 schemas: UpdateReportRequest: type: object additionalProperties: false minProperties: 1 properties: name: type: string minLength: 1 maxLength: 200 description: Display name for the saved report. example: Q2 plan comparison run_ids: type: array minItems: 1 maxItems: 2000 items: type: string description: >- Replacement run IDs. All must belong to the authenticated organization. example: - 8EktrIgaVxn9LfxkIynagX - 9FltuJhbWyoAMgymJzobhY simulation_output_ids: type: array maxItems: 10000 items: type: string description: > Replacement simulation IDs pinning the report to a subset of simulations. When set, this is the report's authoritative scope. example: - AGktrIgaVxn9LfxkIynagX source_human_review_project_id: type: string minLength: 26 maxLength: 26 description: > Human review project the simulations were sourced from; `simulation_output_ids` must belong to it. Omit to leave unchanged — null is rejected, the linkage cannot be cleared via update. example: 01JABCDEFGHJKMNPQRSTVWXYZ0 compare_by: $ref: '#/components/schemas/CompareBy' metadata_key: type: string minLength: 1 maxLength: 200 nullable: true description: >- Required when changing `compare_by` to `metadata`; otherwise omit it. example: customer.plan permissions: $ref: '#/components/schemas/ReportPermission' UpdateReportResponse: type: object required: - report properties: report: $ref: '#/components/schemas/Report' CompareBy: type: string enum: - none - run - agent - mutation - persona - test_case - metadata default: none description: Dimension to group and compare runs by in the report view. example: persona ReportPermission: type: string enum: - PUBLIC - PRIVATE default: PRIVATE description: >- PUBLIC creates a login-free shareable report; PRIVATE keeps it organization-only. example: PRIVATE Report: type: object required: - id - name - run_ids - compare_by - metadata_key - permissions properties: id: type: string minLength: 26 maxLength: 26 description: >- The report's ULID. Open it in the app at //reports/. example: 01JABCDEFGHJKMNPQRSTVWXYZ0 name: type: string description: Display name for the saved report. example: Plan comparison run_ids: type: array maxItems: 2000 items: type: string description: Run IDs included in the saved report. example: - 8EktrIgaVxn9LfxkIynagX - 9FltuJhbWyoAMgymJzobhY simulation_output_ids: type: array maxItems: 10000 items: type: string description: >- Simulation IDs pinning the saved report to a subset of simulations; empty for run-scoped reports. example: - AGktrIgaVxn9LfxkIynagX source_human_review_project_id: type: string nullable: true description: >- Human review project the pinned simulations were sourced from; null when not report-linked. example: 01JABCDEFGHJKMNPQRSTVWXYZ0 compare_by: $ref: '#/components/schemas/CompareBy' metadata_key: type: string nullable: true description: >- Metadata key used for grouping when `compare_by` is `metadata`; null otherwise. example: customer.plan permissions: $ref: '#/components/schemas/ReportPermission' ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' 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 request body details: type: array maxItems: 100 items: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: type: object properties: field: type: string nullable: true description: Field that caused the error, when available. example: metadata_key description: type: string description: Human-readable detail about the error. example: metadata_key is required when compare_by is metadata examples: ReportCreated: value: report: id: 01JABCDEFGHJKMNPQRSTVWXYZ0 name: Plan comparison run_ids: - 8EktrIgaVxn9LfxkIynagX - 9FltuJhbWyoAMgymJzobhY compare_by: metadata metadata_key: customer.plan permissions: PUBLIC responses: BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INVALID_ARGUMENT message: Invalid request body details: - field: metadata_key description: metadata_key is required when compare_by is metadata Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Authentication failed details: - field: x-api-key description: API key is required in the x-api-key header Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PERMISSION_DENIED message: Insufficient permissions details: - field: permissions description: The API key does not include the required report permission. NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Report not found details: - field: report_id description: Report not found or not authorized. 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 while processing the report request ServiceUnavailable: description: Service temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Service temporarily unavailable details: - description: Database routing is temporarily unavailable. Please retry. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication ````