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

# Get a human call

> The call's status and, once it has ended, its times, recording, disposition, analysis and cost.

Scope: `human_calls:read`.



## OpenAPI

````yaml /api-reference/openapi.json get /human-calls/{id}
openapi: 3.1.0
info:
  title: Telleo API
  version: 1.2.0
  description: >-
    Start AI phone calls, or connect your counsellors to contacts, from your own
    systems and get each call's outcome back.
servers:
  - url: https://api.telleo.ai/v1
security:
  - ApiKey: []
tags:
  - name: Calls
  - name: Batches
  - name: Agents
  - name: Human calls
  - name: Credits
  - name: Webhook
paths:
  /human-calls/{id}:
    get:
      tags:
        - Human calls
      summary: Get a human call
      description: >-
        The call's status and, once it has ended, its times, recording,
        disposition, analysis and cost.


        Scope: `human_calls:read`.
      operationId: getHumanCall
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The human call.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanCall'
              example:
                id: hcall_7d2e9b1c4a6f8e0d3b5c7a9e
                object: human_call
                status: completed
                counsellor:
                  id: 5f0c2b7e-8a1d-4c3e-9b6f-1a2b3c4d5e6f
                  name: Priya Sharma
                  email: priya@school.in
                phone_number: '+919876543210'
                contact:
                  name: Asha Verma
                  email: null
                  external_id: lead-8812
                crm_lead_linked: true
                metadata:
                  crm_owner: u_42
                analyze: true
                status_updates: realtime
                created_at: '2026-10-17T05:30:02Z'
                dialed_at: '2026-10-17T05:30:03Z'
                answered_at: '2026-10-17T05:30:21Z'
                ended_at: '2026-10-17T05:36:40Z'
                duration_seconds: 379
                recording_url: >-
                  https://media.example-cdn.com/recordings/abc.mp3?X-Amz-Signature=…
                recording_expires_at: '2026-10-18T05:40:00Z'
                disposition:
                  key: INTERESTED
                  label: Interested
                  notes: Demo on Friday
                  set_at: '2026-10-17T05:37:10Z'
                  set_by: counsellor
                analysis:
                  status: completed
                  summary: >-
                    Asha wants the NEET 2027 weekend batch; demo booked for
                    Friday.
                  short_update: Interested, demo Friday
                  call_type: sales
                  inferred_goal: Book a demo class
                  outcome: interested
                  sentiment: positive
                  conversion_likelihood: high
                  counsellor_rating: 8
                  outcome_rating: 7.5
                  language: hi
                  credits: 0.95
                  completed_at: '2026-10-17T05:39:02Z'
                cost:
                  credits: 6.5
                  billed: true
        '401':
          description: The key is missing, unknown, revoked or expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_api_key:
                  value:
                    error:
                      code: missing_api_key
                      message: Send your API key in the X-API-Key header.
                      request_id: req_8f2c1a7e
                invalid_api_key:
                  value:
                    error:
                      code: invalid_api_key
                      message: This API key is not valid.
                      request_id: req_8f2c1a7e
        '404':
          description: No human call with this id belongs to your account.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    error:
                      code: not_found
                      message: Human call not found.
                      request_id: req_8f2c1a7e
        '429':
          description: Too many requests for this key.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error:
                      code: rate_limited
                      message: Too many requests. Retry after 12 seconds.
                      request_id: req_8f2c1a7e
components:
  headers:
    RequestId:
      schema:
        type: string
      description: Unique id of this request. Quote it to support.
  schemas:
    HumanCall:
      type: object
      properties:
        id:
          type: string
          example: hcall_7d2e9b1c4a6f8e0d3b5c7a9e
        object:
          type: string
          const: human_call
        status:
          type: string
          enum:
            - queued
            - ringing_counsellor
            - connecting
            - in_progress
            - completed
            - no_answer
            - busy
            - failed
            - canceled
        status_reason:
          type: string
          description: Why a call failed, in plain words. Present only when there is one.
        no_answer_by:
          type:
            - string
            - 'null'
          enum:
            - counsellor
            - contact
            - null
          description: >-
            Only on `no_answer` / `busy`: which phone did not pick up, when the
            provider says so.
        counsellor:
          type: object
          properties:
            id:
              type: string
            name:
              type:
                - string
                - 'null'
            email:
              type:
                - string
                - 'null'
        phone_number:
          type: string
        contact:
          $ref: '#/components/schemas/Contact'
        crm_lead_linked:
          type: boolean
          description: >-
            The call was filed on the one lead in your account with this number
            (it shows on the lead's timeline).
        metadata:
          type: object
          additionalProperties: true
        analyze:
          type: boolean
        status_updates:
          type: string
          enum:
            - realtime
            - final_only
            - delayed
          description: >-
            How live `status` is on your provider: Vacademy Voice `realtime`,
            Exotel `final_only`, Airtel `delayed` (after its call record is
            imported).
        created_at:
          type: string
          format: date-time
        dialed_at:
          type:
            - string
            - 'null'
          format: date-time
        answered_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the contact picked up, when known.
        ended_at:
          type:
            - string
            - 'null'
          format: date-time
        duration_seconds:
          type:
            - integer
            - 'null'
        recording_url:
          type:
            - string
            - 'null'
          description: >-
            A temporary link to the recording (24 hours). Fetch the call again
            for a fresh link.
        recording_expires_at:
          type:
            - string
            - 'null'
          format: date-time
        disposition:
          $ref: '#/components/schemas/HumanCallDisposition'
        analysis:
          $ref: '#/components/schemas/HumanCallAnalysis'
        cost:
          type:
            - object
            - 'null'
          description: >-
            `null` while the call runs. Only Vacademy Voice talk time is charged
            to your credits; Exotel and Airtel bill you directly.
          properties:
            credits:
              type: number
            billed:
              type: boolean
            note:
              type: string
              enum:
                - billed_by_provider
              description: Present when the call ran on your own carrier account.
        idempotent_replay:
          type: boolean
          description: >-
            Only on `POST /human-calls`: `true` when this is the call created by
            an earlier request with the same `Idempotency-Key`.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable code. Branch on this, not on the message.
              example: invalid_request
            message:
              type: string
              description: A sentence you can log or show to an operator.
            request_id:
              type: string
              description: Quote this when you contact support.
            details:
              type: object
              additionalProperties: true
              description: >-
                Extra context, e.g. `errors: [{field, message}]` for validation
                errors or `call_id` for conflicts.
    Contact:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          maxLength: 120
          description: >-
            How the agent addresses the person. Fills `{{name}}` in the agent's
            script.
        email:
          type:
            - string
            - 'null'
          format: email
        external_id:
          type:
            - string
            - 'null'
          maxLength: 255
          description: >-
            Your own id for this person or lead (CRM record id). Echoed back and
            filterable on `GET /calls`.
    HumanCallDisposition:
      type:
        - object
        - 'null'
      description: The outcome recorded by the counsellor or by you. `null` until set.
      properties:
        key:
          type: string
          example: INTERESTED
        label:
          type:
            - string
            - 'null'
        notes:
          type:
            - string
            - 'null'
        set_at:
          type:
            - string
            - 'null'
          format: date-time
        set_by:
          type:
            - string
            - 'null'
          enum:
            - counsellor
            - api
            - null
    HumanCallAnalysis:
      type: object
      description: >-
        AI analysis of the conversation. Fields beyond `status` are present once
        it is `completed`.
      properties:
        status:
          type: string
          enum:
            - not_requested
            - pending
            - completed
            - failed
        reason:
          type: string
          description: >-
            With `failed`: `not_connected`, `no_recording`,
            `insufficient_credits`, `empty_transcript`, `analysis_error`… A
            temporary error is retried (up to 4 attempts) and stays `pending`
            meanwhile.
        summary:
          type:
            - string
            - 'null'
        short_update:
          type:
            - string
            - 'null'
          description: A few words for a list view.
        call_type:
          type:
            - string
            - 'null'
        inferred_goal:
          type:
            - string
            - 'null'
          description: >-
            What the counsellor was trying to achieve, inferred from the
            conversation.
        outcome:
          type:
            - string
            - 'null'
          description: The call's outcome in a word or two, e.g. `interested`.
        sentiment:
          type:
            - string
            - 'null'
          description: The contact's sentiment.
        conversion_likelihood:
          type:
            - string
            - 'null'
        counsellor_rating:
          type:
            - number
            - 'null'
          description: How well the counsellor pursued the call's goal (0–10).
        outcome_rating:
          type:
            - number
            - 'null'
          description: How good the outcome was (0–10).
        language:
          type:
            - string
            - 'null'
        credits:
          type:
            - number
            - 'null'
          description: Credits charged for this analysis.
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your AI calling API key (`vak_call_…`). `Authorization: Bearer <key>`
        also works.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.