> ## 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 metrics > List metric results for a simulation. ## OpenAPI ````yaml get /simulations/{simulation_id}/metrics 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/{simulation_id}/metrics: get: tags: - Metric Outputs summary: List metrics description: List metric results for a simulation. operationId: listMetrics parameters: - name: simulation_id in: path required: true schema: type: string minLength: 22 maxLength: 27 description: The simulation ID example: 6djpxGeYTvl7JdvhGwlYfV - name: filter in: query required: false schema: type: string description: > Filter expression syntax. Supported fields: `status`, `metric_id`, `metric_name`, `value`, `create_time`, `start_time`, `end_time` Operators: `=`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR` Values may be unquoted or double-quoted. Values containing spaces must be quoted (e.g., `status="IN PROGRESS"`). example: status=COMPLETED AND metric_name=accuracy - 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: metric_name description: > Sort order specification. Format: `field` or `-field` (descending) Supported fields: `metric_name`, `create_time`, `value`, `start_time`, `end_time` example: metric_name responses: '200': description: List of metric outputs content: application/json: schema: $ref: '#/components/schemas/ListMetricsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: ListMetricsResponse: type: object required: - metrics properties: metrics: type: array items: $ref: '#/components/schemas/SimpleMetricOutput' description: Array of simplified metric outputs next_page_token: type: string description: Token for fetching next page of results (if more exist) example: eyJvZmZzZXQiOiA1MH0= SimpleMetricOutput: type: object required: - metric_output_id - metric_id - status properties: metric_output_id: type: string minLength: 26 maxLength: 26 description: Unique metric output identifier (26-char ULID) example: 01JCQR8Z9PQSTNVWXY12345678 metric_id: type: string description: Metric definition identifier example: abc123xyz789 metric_version_ulid: type: string nullable: true minLength: 26 maxLength: 26 description: >- ULID of the metric version this output was scored against (null for outputs produced before metric versioning landed). example: 01JCQR8Z9PQSTNVWXY12345678 value: description: >- Metric value (float, string, or list of strings). Can be null if not yet computed. example: 0.85 oneOf: - type: number - type: string - type: array items: type: string status: type: string enum: - IN QUEUE - IN PROGRESS - COMPLETED - FAILED description: Current status of the metric computation example: COMPLETED explanation: type: string nullable: true description: >- The LLM judge's reasoning for this metric output, as a flat string. Null for metrics that produce no explanation (non-judge metrics) or when the output is not yet computed. This is a convenience surfacing of the reasoning that otherwise lives nested under result.llm.answer_explanation (or result.explanation); it is populated in both the list and single-output responses so callers do not have to request the full result object to read it. example: >- The agent never confirmed the caller's address before ending the call. subvalues_by_timestamp: type: array nullable: true items: $ref: '#/components/schemas/SubvalueByTimestamp' description: Time-series metric values anchored to time ranges result: type: object nullable: true additionalProperties: true description: >- Structured metric result. Its keys depend on the metric type — for example llm for LLM-judge metrics, or stats/count for numeric metrics. The llm key is present only for LLM-judge metrics: the judge's reasoning is at result.llm.answer_explanation and the evaluation prompt at result.llm.prompt. Null for metrics that produce no structured result. example: llm: answer_explanation: >- The agent never confirmed the caller's address before ending the call. prompt: Did the agent confirm the caller's address? runtime_metadata: type: object nullable: true additionalProperties: true description: >- How the metric was computed at runtime, such as model version and trace context. Null when not recorded. ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorInfo' SubvalueByTimestamp: type: object required: - start_offset - end_offset - output_type properties: start_offset: type: number description: Start position in seconds example: 0 end_offset: type: number description: End position in seconds example: 2.5 output_type: type: string enum: - float - string - set description: Value type example: float float_value: type: number description: Numeric value (when output_type is float) default: 0 example: 0.85 string_value: type: string description: String value (when output_type is string) default: '' example: '' role: type: string nullable: true description: Speaker role for this interval (e.g. user, assistant) example: assistant message_index: type: integer nullable: true description: 0-based transcript message index example: 3 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 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Agent not found details: - field: agent_id description: Agent 'gk3jK9mPq2xRt5vW8yZaBc' does not exist 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. ````