> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxfra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Call Evaluations

> Returns evaluation resources for calls in the authenticated organization.
Supports the same pagination and call filters as `GET /v1/calls`, but each item includes explicit evaluation workflow state and the currently available evaluation payload for that call.


Use this endpoint for dashboard tables, review queues, and date-range reports that need evaluation workflow state across many calls.

Each item includes lightweight call context plus the evaluation state and payload available for that call at read time. If you need one stable record for a single call, use [/api-reference/calls/get-evaluations](/api-reference/calls/get-evaluations).


## OpenAPI

````yaml GET /v1/calls/evaluations
openapi: 3.1.0
info:
  title: Voxfra Management API
  description: >
    Tenant-facing REST API for integrating with Voxfra's voice intelligence
    infrastructure.

    Use this API to read call data, manage clients, and build partner
    dashboards.


    ## Authentication


    All endpoints except `GET /health` require an API key passed in the
    `X-API-Key` header.

    API keys are scoped to a single organization — all responses are
    automatically filtered to your org.


    Keys are issued by your Voxfra account manager or via the Voxfra admin
    console.
  version: 1.0.0
  contact:
    name: Voxfra Support
    email: support@voxfra.com
  license:
    name: Proprietary
    url: https://voxfra.com/terms
servers:
  - url: https://mgmt-api.voxfra.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Health
    description: System status
  - name: Auth
    description: Verify and inspect the current API key
  - name: Clients
    description: >-
      Read and provision clients (dealerships, clinics, etc.) within your
      organization
  - name: Calls
    description: Access call records ingested through voxfra
  - name: Customers
    description: >-
      Access tenant-scoped customer records deduplicated within organization and
      client boundaries
paths:
  /v1/calls/evaluations:
    get:
      tags:
        - Calls
      summary: List call evaluations
      description: >
        Returns evaluation resources for calls in the authenticated
        organization.

        Supports the same pagination and call filters as `GET /v1/calls`, but
        each item includes explicit evaluation workflow state and the currently
        available evaluation payload for that call.
      operationId: listCallEvaluations
      parameters:
        - name: client_id
          in: query
          required: false
          description: Filter by client UUID
          schema:
            type: string
            format: uuid
          example: 00000000-0000-0000-0000-000000000002
        - name: start_date
          in: query
          required: false
          description: ISO 8601 date — return calls on or after this date
          schema:
            type: string
            format: date-time
          example: '2026-01-01T00:00:00Z'
        - name: end_date
          in: query
          required: false
          description: ISO 8601 date — return calls on or before this date
          schema:
            type: string
            format: date-time
          example: '2026-01-31T23:59:59Z'
        - name: limit
          in: query
          required: false
          description: Number of results to return (max 200, default 50)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: offset
          in: query
          required: false
          description: Number of results to skip for pagination
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Paginated list of call evaluations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallEvaluationListResponse'
              example:
                data:
                  - status: completed
                    updated_at: '2026-05-08T10:18:00Z'
                    call:
                      id: 11111111-1111-1111-1111-111111111111
                      client_id: 00000000-0000-0000-0000-000000000002
                      created_at: '2026-05-08T10:00:00Z'
                      caller_full_name: Jane Smith
                      caller_phone_number: '+15551234567'
                      call_summary: Customer asked about service availability.
                    lead_quality:
                      state: completed
                      completed_at: '2026-05-08T10:15:00Z'
                      result:
                        overall_score: 4.5
                        sentiment:
                          value: positive
                          rationale: Caller remained upbeat throughout.
                        flags:
                          negative_call: false
                          human_review_required: false
                          review_reason: null
                        scores:
                          lead_completion:
                            score: 5
                            rationale: null
                          clarity_politeness:
                            score: 4
                            rationale: The agent stayed concise and polite.
                          relevance_questions:
                            score: 4
                            rationale: Questions matched the caller intent.
                          objection_handling:
                            score: 3
                            rationale: Handled objections but missed a follow-up.
                          naturalness:
                            score: 4
                            rationale: The delivery sounded conversational.
                          lead_intent:
                            score: 5
                            rationale: Caller clearly wanted a booking.
                          failure_risk:
                            score: 2
                            rationale: Only minor drop-off risk surfaced.
                    prompt_adherence:
                      state: completed
                      completed_at: '2026-05-08T10:18:00Z'
                      result:
                        score: 4
                        critical_failures_summary: null
                        what_went_well:
                          - Used the approved greeting
                          - Captured callback preference
                        what_went_wrong:
                          - Skipped one pricing disclaimer
                        recommendations_for_improvement:
                          - Ask the disclaimer question before transfer
                        prompt:
                          system_instruction: >-
                            Always greet the caller and confirm callback
                            preference.
                          system_variables:
                            dealership_name: Northside Auto
                            escalation_phone: '+14165550123'
                pagination:
                  limit: 50
                  offset: 0
                  total: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: client_id not found or does not belong to this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Client not found
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CallEvaluationListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CallEvaluationResource'
        pagination:
          type: object
          properties:
            limit:
              type: integer
            offset:
              type: integer
            total:
              type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    CallEvaluationResource:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CallEvaluationStatus'
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        call:
          $ref: '#/components/schemas/CallEvaluationCallContext'
        lead_quality:
          $ref: '#/components/schemas/LeadQualityEvaluationDomain'
        prompt_adherence:
          $ref: '#/components/schemas/PromptAdherenceEvaluationDomain'
    CallEvaluationStatus:
      type: string
      enum:
        - pending
        - partial
        - completed
    CallEvaluationCallContext:
      type: object
      properties:
        id:
          type: string
          format: uuid
        client_id:
          type: string
          format: uuid
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        caller_full_name:
          type:
            - string
            - 'null'
        caller_phone_number:
          type:
            - string
            - 'null'
        call_summary:
          type:
            - string
            - 'null'
    LeadQualityEvaluationDomain:
      type: object
      properties:
        state:
          $ref: '#/components/schemas/CallEvaluationDomainState'
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        result:
          oneOf:
            - $ref: '#/components/schemas/LeadQualityEvaluationResult'
            - type: 'null'
    PromptAdherenceEvaluationDomain:
      type: object
      properties:
        state:
          $ref: '#/components/schemas/CallEvaluationDomainState'
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        result:
          oneOf:
            - $ref: '#/components/schemas/PromptAdherenceEvaluationResult'
            - type: 'null'
    CallEvaluationDomainState:
      type: string
      enum:
        - pending
        - completed
    LeadQualityEvaluationResult:
      type: object
      properties:
        overall_score:
          type:
            - number
            - 'null'
        sentiment:
          $ref: '#/components/schemas/LeadQualitySentiment'
        flags:
          $ref: '#/components/schemas/LeadQualityFlags'
        scores:
          $ref: '#/components/schemas/LeadQualityScores'
    PromptAdherenceEvaluationResult:
      type: object
      properties:
        score:
          type:
            - number
            - 'null'
        critical_failures_summary:
          type:
            - string
            - 'null'
        what_went_well:
          $ref: '#/components/schemas/JsonValue'
        what_went_wrong:
          $ref: '#/components/schemas/JsonValue'
        recommendations_for_improvement:
          $ref: '#/components/schemas/JsonValue'
        prompt:
          $ref: '#/components/schemas/PromptReference'
    LeadQualitySentiment:
      type: object
      properties:
        value:
          type: string
          enum:
            - positive
            - neutral
            - negative
            - mixed
        rationale:
          type:
            - string
            - 'null'
    LeadQualityFlags:
      type: object
      properties:
        negative_call:
          type: boolean
        human_review_required:
          type: boolean
        review_reason:
          type:
            - string
            - 'null'
    LeadQualityScores:
      type: object
      properties:
        lead_completion:
          $ref: '#/components/schemas/EvaluationScoreWithRationale'
        clarity_politeness:
          $ref: '#/components/schemas/EvaluationScoreWithRationale'
        relevance_questions:
          $ref: '#/components/schemas/EvaluationScoreWithRationale'
        objection_handling:
          $ref: '#/components/schemas/EvaluationScoreWithRationale'
        naturalness:
          $ref: '#/components/schemas/EvaluationScoreWithRationale'
        lead_intent:
          $ref: '#/components/schemas/EvaluationScoreWithRationale'
        failure_risk:
          $ref: '#/components/schemas/EvaluationScoreWithRationale'
    JsonValue:
      description: Arbitrary JSON value.
      oneOf:
        - type: string
        - type: number
        - type: boolean
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
        - type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        - type: 'null'
    PromptReference:
      type: object
      properties:
        system_instruction:
          type:
            - string
            - 'null'
        system_variables:
          type:
            - object
            - 'null'
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
    EvaluationScoreWithRationale:
      type: object
      properties:
        score:
          type:
            - number
            - 'null'
        rationale:
          type:
            - string
            - 'null'
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unauthorized
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Internal Server Error
            message: Unexpected error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Your Voxfra management API key. Passed as a request header.

        Format: `vox_mgmt_<random>`

````