> ## 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.

# Get Call Evaluations

> Returns the evaluation artifact for a single call.
The call itself must belong to the authenticated organization. Missing evaluation rows are modeled inside the payload with `pending` or `partial` workflow state rather than returning `404`.


Use this endpoint to retrieve the evaluation artifact for a single call.

It exposes explicit workflow state, score and rationale fields for lead quality, and the evaluated prompt snapshot for prompt-adherence reviews when available. A missing call returns `404`; a call with no finished evaluation rows still returns `200` with `pending` or `partial` state.


## OpenAPI

````yaml GET /v1/calls/{id}/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/{id}/evaluations:
    get:
      tags:
        - Calls
      summary: Get call evaluations
      description: >
        Returns the evaluation artifact for a single call.

        The call itself must belong to the authenticated organization. Missing
        evaluation rows are modeled inside the payload with `pending` or
        `partial` workflow state rather than returning `404`.
      operationId: getCallEvaluations
      parameters:
        - name: id
          in: path
          required: true
          description: Call UUID
          schema:
            type: string
            format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Call evaluation resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallEvaluationDetailResponse'
              example:
                data:
                  call_id: 11111111-1111-1111-1111-111111111111
                  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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Call not found or does not belong to this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Call not found
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CallEvaluationDetailResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CallEvaluationDetail'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    CallEvaluationDetail:
      allOf:
        - $ref: '#/components/schemas/CallEvaluationResource'
        - type: object
          properties:
            call_id:
              type: string
              format: uuid
    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>`

````