> ## 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 simulation metric output(s) > Retrieve metric output(s) for a simulation by ID. The path segment accepts two ID types and returns different response shapes: - **26-char MetricOutput ULID**: returns a single metric output as `{ "metric": {...} }`. - **22-char Metric definition ID**: returns every output for that metric on the simulation as `{ "metric_outputs": [...] }`. Clients should branch on the input ID length they passed. **Retrieving test-metric results:** after calling `POST /v1/metrics/{metric_id}/test`, poll this endpoint using the same simulation output ID you tested against as `simulation_id`, plus the returned 26-char `metric_output_ulid`. The response includes a `status` field (`IN QUEUE`, `IN PROGRESS`, `COMPLETED`, `FAILED`) — poll until it is terminal. Test-metric outputs belong to the simulation they ran against, so they are retrieved here, not via the conversations endpoint. ## OpenAPI ````yaml /api-reference/v1/simulations-v1.yaml get /simulations/{simulation_id}/metrics/{metric_output_id} 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/{metric_output_id}: get: tags: - Metric Outputs summary: Get simulation metric output(s) description: | Retrieve metric output(s) for a simulation by ID. The path segment accepts two ID types and returns different response shapes: - **26-char MetricOutput ULID**: returns a single metric output as `{ "metric": {...} }`. - **22-char Metric definition ID**: returns every output for that metric on the simulation as `{ "metric_outputs": [...] }`. Clients should branch on the input ID length they passed. **Retrieving test-metric results:** after calling `POST /v1/metrics/{metric_id}/test`, poll this endpoint using the same simulation output ID you tested against as `simulation_id`, plus the returned 26-char `metric_output_ulid`. The response includes a `status` field (`IN QUEUE`, `IN PROGRESS`, `COMPLETED`, `FAILED`) — poll until it is terminal. Test-metric outputs belong to the simulation they ran against, so they are retrieved here, not via the conversations endpoint. operationId: getMetric parameters: - name: simulation_id in: path required: true schema: type: string minLength: 22 maxLength: 27 description: The simulation ID example: 7ekqyHfZUwm8KewjHxmZgW - name: metric_output_id in: path required: true schema: type: string minLength: 22 maxLength: 26 description: > Either a 26-char MetricOutput ULID or a 22-char Metric definition ID. See endpoint description for response shape per ID type. example: 01ARZ3NDEKTSV4RRFFQ69G5FAV responses: '200': description: | Metric output details. Single object when called with a 26-char ULID, collection object when called with a 22-char metric_id. content: application/json: schema: oneOf: - $ref: '#/components/schemas/GetMetricOutputResponse' - $ref: '#/components/schemas/MetricOutputCollection' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: GetMetricOutputResponse: type: object required: - metric description: >- Single metric output (returned when {metric_output_id} is a 26-char ULID) properties: metric: $ref: '#/components/schemas/SimpleMetricOutput' MetricOutputCollection: type: object required: - metric_outputs description: | All MetricOutput rows for a given Metric on this simulation. Returned when the path {metric_output_id} is a 22-char Metric definition ID. properties: metric_outputs: type: array items: $ref: '#/components/schemas/SimpleMetricOutput' 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: 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. ````