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

# Get a call

> Read a call's detail, variables, transcript and signed recording links.

> [!NOTE]
>
> This capability is in **beta**. Behavior can change before general availability.

Use the callId as the path ID. The transcript contains at most 1,000 entries, with transcriptTruncated indicating omitted content.

Privacy protections apply unless the key has **Read protected call details**.

## Related pages

* [Authentication](https://hellotars.com/docs/developer/authentication.md)


## OpenAPI

````yaml api-reference/openapi.json GET /api/v1/calls/{id}
openapi: 3.1.0
info:
  title: Tars API
  version: '1'
  description: >-
    Start conversations, send messages, manage contacts, send campaign messages,
    place and read calls, and manage webhook destinations.
servers:
  - url: https://us.api.hellotars.com
    description: United States
  - url: https://eu.api.hellotars.com
    description: European Union
  - url: https://in.api.hellotars.com
    description: India
  - url: https://qa.api.hellotars.com
    description: Qatar
security:
  - bearerAuth: []
tags:
  - name: Conversations
    description: Start conversations at a chat agent's trigger step.
  - name: Messages
    description: Send channel messages as a chat agent.
  - name: Contacts
    description: Read and manage contacts.
  - name: Campaigns
    description: Send webhook campaign messages.
  - name: Calls
    description: Place, read and manage phone calls.
  - name: Agents
    description: Read chat agents and voice agents.
  - name: Phone numbers
    description: Read your phone numbers.
  - name: Artefacts
    description: Download call recordings.
  - name: Webhooks
    description: Manage webhook destinations.
paths:
  /api/v1/calls/{id}:
    get:
      tags:
        - Calls
      summary: Get a call
      description: >-
        Reads one call with its variables, transcript and signed recording
        links.


        Requires the Read calls permission (`calls:read`).


        Protected values are shown only with the Read protected call details
        permission (`calls:read_protected`).
      operationId: getCall
      parameters:
        - name: id
          in: path
          required: true
          description: The call id (call_…).
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        '200':
          description: The call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallDetail'
        '400':
          description: validation_failed
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: unauthorized, invalid_key
          headers:
            WWW-Authenticate:
              schema:
                const: Bearer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: >-
            organization_inactive, billing_locked, permission_missing,
            resource_not_allowed
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: not_found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '405':
          description: method_not_allowed
          headers:
            Allow:
              description: The methods this path accepts.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: wrong_region, call_content_deleted
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: rate_limited
          headers:
            Retry-After:
              description: Whole seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: internal_error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearerAuth: []
components:
  schemas:
    CallDetail:
      type: object
      description: >-
        One call with its variables, transcript and signed recording links.
        Protected values are null unless the key has the Read protected call
        details permission.
      properties:
        callId:
          type: string
          description: The call id (call_…).
        kind:
          type: string
          enum:
            - retained
            - deleted
        agentId:
          anyOf:
            - type: string
            - type: 'null'
        agentName:
          anyOf:
            - type: string
            - type: 'null'
        agentVersion:
          anyOf:
            - type: number
            - type: 'null'
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
        contactId:
          anyOf:
            - type: string
            - type: 'null'
        source:
          type: string
        direction:
          type: string
        status:
          type: string
        displayStatus:
          type: string
        timing:
          type: object
        variables:
          type: object
        transcript:
          type: array
          items:
            type: object
        transcriptTruncated:
          type: boolean
        recordings:
          type: array
          items:
            type: object
      required:
        - callId
        - kind
        - status
    Problem:
      type: object
      description: >-
        RFC 9457 problem details. Clients switch on code, never on title or
        detail.
      properties:
        title:
          type: string
          description: The catalogue title of code.
        status:
          type: integer
          description: The HTTP status.
        detail:
          type: string
          description: A sentence about this failure, for a developer.
        instance:
          type: string
          description: The request id (req_…). Quote it when you contact support.
        code:
          type: string
          enum:
            - invalid_json
            - validation_failed
            - variable_key_not_allowed
            - invalid_variable_value
            - cursor_expired
            - cursor_mismatch
            - campaign_mode_invalid
            - unauthorized
            - invalid_key
            - session_invalid
            - insufficient_balance
            - organization_inactive
            - billing_locked
            - permission_missing
            - resource_not_allowed
            - entitlement_missing
            - origin_not_allowed
            - recaptcha_failed
            - consent_revoked
            - us_marketing_blocked
            - channel_test_mode
            - quota_exceeded
            - forbidden
            - not_found
            - method_not_allowed
            - wrong_region
            - conflict
            - contact_exists
            - idempotency_key_reuse
            - agent_unavailable
            - call_not_live
            - call_still_live
            - call_content_deleted
            - invalid_state
            - campaign_paused
            - template_version_drift
            - channel_unavailable
            - artefact_deleted
            - campaign_gone
            - payload_too_large
            - template_not_approved
            - channel_misconfigured
            - channel_reauth_required
            - meta_rejected
            - rate_limited
            - concurrency_limit_reached
            - worker_busy
            - meta_rate_limited
            - internal_error
            - upstream_unavailable
            - meta_unavailable
            - worker_not_deployed
            - worker_unavailable
        retryable:
          type: boolean
          description: true when the same request can succeed later.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
        required:
          type: string
          description: The permission the key lacks (permission_missing).
        region:
          type: string
          description: The organization's region (wrong_region).
        field:
          type: string
          enum:
            - email
            - phone
        contactId:
          type: string
          description: The contact that already has the email or phone.
        callId:
          type: string
        reason:
          type: string
      required:
        - title
        - status
        - detail
        - instance
        - code
        - retryable
    ValidationIssue:
      type: object
      description: One field that failed validation.
      properties:
        path:
          type: string
          description: >-
            Dotted path of the field (template.parameters.body.0), the query
            parameter name, or an empty string for the whole body.
        code:
          type: string
          description: >-
            Why the field failed, for example required, unknown_field,
            out_of_range or template_param_missing.
        message:
          type: string
      required:
        - path
        - code
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key (`tars_sk_…`) sent as `Authorization: Bearer <key>`. Each
        operation names the permission it needs. Create keys in Settings →
        Integrations → API keys.

````

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