openapi: 3.0.3
info:
  title: Coval Agents Metric Outputs API
  version: 1.0.0
  description: '

    Manage configurations for simulations and evaluations.

    '
  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: Metric Outputs
  description: Retrieve metric computation results for simulations
paths:
  /simulations/{simulation_id}/metrics:
    get:
      operationId: listMetrics
      summary: List metrics
      description: List metric results for a simulation.
      tags:
      - Metric Outputs
      security:
      - ApiKeyAuth: []
      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'
  /simulations/{simulation_id}/metrics/{metric_output_id}:
    get:
      operationId: getMetric
      summary: Get simulation metric output(s)
      description: "Retrieve metric output(s) for a simulation by ID. The path segment\naccepts two ID types and returns different response shapes:\n\n- **26-char MetricOutput ULID**: returns a single metric output as\n  `{ \"metric\": {...} }`.\n- **22-char Metric definition ID**: returns every output for that\n  metric on the simulation as `{ \"metric_outputs\": [...] }`.\n\nClients should branch on the input ID length they passed.\n\n**Retrieving test-metric results:** after calling\n`POST /v1/metrics/{metric_id}/test`, poll this endpoint using the same\nsimulation output ID you tested against as `simulation_id`, plus the\nreturned 26-char `metric_output_ulid`. The response includes a `status`\nfield (`IN QUEUE`, `IN PROGRESS`, `COMPLETED`, `FAILED`) — poll until it\nis terminal. Test-metric outputs belong to the simulation they ran\nagainst, so they are retrieved here, not via the conversations endpoint.\n"
      tags:
      - Metric Outputs
      security:
      - ApiKeyAuth: []
      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'
components:
  schemas:
    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.
    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
    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'
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorInfo'
    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'
    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
    SubvalueByTimestamp:
      type: object
      required:
      - start_offset
      - end_offset
      - output_type
      properties:
        start_offset:
          type: number
          description: Start position in seconds
          example: 0.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.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
    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=
  responses:
    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.
    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
    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
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication
x-visibility: external