> ## 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 annotations with metric outputs > Review annotations grouped by metric plus the latest pipeline metric outputs, scoped by any of metric_ids / simulation_output_ids / project_ids (all optional). Offset-paginated via page_token / page_size. ## OpenAPI ````yaml /api-reference/v1/reviews-v1.yaml post /review-annotations:withMetricOutputs openapi: 3.0.3 info: title: Coval Reviews API version: 1.0.0 description: > Manage human review annotations and projects for AI evaluation quality assurance. **Annotations** are individual review tasks assigned to reviewers, linked to a simulation output and metric. Reviewers provide ground-truth values and notes. **Projects** group annotations by linking sets of simulations, metrics, and assignees. Creating a project auto-generates annotations for every (simulation, metric, assignee) combination. Key concepts: - Ground truth updates auto-complete annotations (FR-4) - Resource naming: `review-annotations/{id}`, `review-projects/{id}` 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: Review Annotations description: Annotation CRUD operations - name: Review Projects description: Project CRUD operations paths: /review-annotations:withMetricOutputs: post: tags: - Review Annotations summary: Get annotations with metric outputs description: >- Review annotations grouped by metric plus the latest pipeline metric outputs, scoped by any of metric_ids / simulation_output_ids / project_ids (all optional). Offset-paginated via page_token / page_size. operationId: getReviewAnnotationsWithMetricOutputs requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/GetAnnotationsWithMetricOutputsRequest' responses: '200': description: Annotations retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetAnnotationsWithMetricOutputsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - ApiKeyAuth: [] components: schemas: GetAnnotationsWithMetricOutputsRequest: type: object additionalProperties: false properties: metric_id: type: string nullable: true metric_ids: type: array nullable: true maxItems: 10000 items: type: string simulation_output_ids: type: array nullable: true maxItems: 10000 items: type: string project_ids: type: array nullable: true maxItems: 1000 items: type: string filter_archived: type: boolean default: false include_metric_output_details: type: boolean default: true include_audio_lengths: type: boolean default: true page_size: type: integer nullable: true minimum: 1 maximum: 1000 page_token: type: string nullable: true GetAnnotationsWithMetricOutputsResponse: type: object required: - annotations - metric_outputs - audio_lengths_by_simulation_output_id properties: annotations: type: object description: Annotations keyed by metric ID. additionalProperties: type: array items: $ref: '#/components/schemas/ReviewAnnotationResource' metric_outputs: type: object description: >- Latest pipeline metric output keyed by metric ID then simulation output ID. additionalProperties: type: object additionalProperties: $ref: '#/components/schemas/ReviewMetricOutputForAnnotationResource' audio_lengths_by_simulation_output_id: type: object additionalProperties: type: number nullable: true next_page_token: type: string nullable: true ReviewAnnotationResource: type: object description: A single review annotation resource. required: - name - id - simulation_output_id - metric_id - assignee - status - completion_status - priority - create_time - update_time properties: name: type: string description: 'Resource name: review-annotations/{id}' example: review-annotations/abc123def456ghi789jklm id: type: string description: Unique annotation ID example: abc123def456ghi789jklm simulation_output_id: type: string description: Linked simulation output ID metric_id: type: string description: Linked metric ID assignee: type: string description: Email of the assigned reviewer ground_truth_float_value: type: number format: float nullable: true description: Reviewer-provided ground truth numeric value ground_truth_string_value: type: string nullable: true description: Reviewer-provided ground truth string value ground_truth_subvalues_by_timestamp: type: array nullable: true description: Reviewer-provided ground truth subvalues keyed by timestamp items: type: object reviewer_notes: type: string nullable: true description: Free-text reviewer notes status: $ref: '#/components/schemas/AnnotationStatus' completion_status: $ref: '#/components/schemas/CompletionStatus' priority: $ref: '#/components/schemas/AnnotationPriority' create_time: type: string format: date-time description: Creation timestamp (ISO 8601) update_time: type: string format: date-time description: Last update timestamp (ISO 8601) ReviewMetricOutputForAnnotationResource: type: object required: - created_at properties: output_type: type: string nullable: true float_value: type: number nullable: true string_value: type: string nullable: true set_value: type: array nullable: true items: type: string error_status: type: string nullable: true created_at: type: string format: date-time explanation: type: string nullable: true result_json: nullable: true subvalues_by_timestamp: nullable: true metric_version_number: type: integer nullable: true metric_version_ulid: type: string nullable: true ErrorResponse: type: object properties: error: type: object properties: code: type: string description: Error code example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Invalid request parameter details: type: array description: Detailed error information items: type: object properties: field: type: string nullable: true description: Field that caused the error description: type: string description: Detailed error description AnnotationStatus: type: string enum: - ACTIVE - ARCHIVED description: 'Annotation lifecycle status: ACTIVE (default) or ARCHIVED' CompletionStatus: type: string enum: - PENDING - COMPLETED description: 'Annotation completion status: PENDING or COMPLETED' AnnotationPriority: type: string enum: - PRIORITY_PRIMARY - PRIORITY_STANDARD default: PRIORITY_STANDARD description: Annotation priority level responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INVALID_ARGUMENT message: Invalid request body details: - field: simulation_output_id description: simulation_output_id is required Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Authentication failed details: - field: X-API-Key description: Invalid or missing API key Forbidden: description: Insufficient permissions 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 reviews permission. 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 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: Organization API key for authentication ````