# List calls with transcripts

Retrieve calls by a list of conversation ids and include transcripts when available.
A maximum of 20 `conversation_ids` can be provided. If none are provided or more than 20 are provided, a 400 error is returned.
Requires the `read_conversations` OAuth scope.

Endpoint: POST /calls/search
Version: 2.17
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)

## Request fields (application/json):

  - `conversation_ids` (array, required)
    A list of conversation ids to fetch calls for. Maximum 20.

## Response 200 fields (application/json):

  - `type` (string)
    Example: list

  - `data` (array)

  - `data.type` (string)
    String representing the object's type. Always has the value `call`.
    Example: call

  - `data.id` (string)
    The id of the call.
    Example: 123

  - `data.conversation_id` (string)
    The id of the conversation associated with the call, if any.
    Example: 456

  - `data.admin_id` (string)
    The id of the admin associated with the call, if any.
    Example: 789

  - `data.contact_id` (string)
    The id of the contact associated with the call, if any.
    Example: 6762f0dd1bb69f9f2193bb83

  - `data.state` (string)
    The current state of the call.
    Example: ended

  - `data.initiated_at` (any)

  - `data.recording_url` (string)
    API URL to download or redirect to the call recording if available.
    Example: https://api.intercom.io/calls/123/recording

  - `data.transcription_url` (string)
    API URL to download or redirect to the call transcript if available.
    Example: https://api.intercom.io/calls/123/transcript

  - `data.call_type` (string)
    The type of call.
    Example: phone

  - `data.direction` (string)
    The direction of the call.
    Example: outbound

  - `data.ended_reason` (string)
    The reason for the call end, if applicable.
    Example: missed

  - `data.phone` (string)
    The phone number involved in the call, in E.164 format.
    Example: +15551234567

  - `data.fin_recording_url` (string)
    API URL to the AI Agent (Fin) call recording if available.

  - `data.fin_transcription_url` (string)
    API URL to the AI Agent (Fin) call transcript if available.

  - `data.duration` (integer)
    Total call duration in seconds from the caller's perspective. For inbound calls, measured from initiated to ended. For outbound calls, measured from answered to ended. Null until the call ends, and for outbound calls that were never answered.
    Example: 900

  - `data.talk_time` (integer)
    Total time in seconds the agent and customer were connected.
    Example: 300

  - `data.queue_time` (integer)
    Total time in seconds the caller waited in queue before connecting, when assigned to a team.
    Example: 45

  - `data.hold_time` (integer)
    Total time in seconds the caller was placed on hold during the call.
    Example: 60

  - `data.transcript` (array)
    The call transcript if available, otherwise an empty array.

  - `data.transcript_status` (string)
    The status of the transcript if available.

## Response 400 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (any, required)
    A string indicating the kind of error, used to further qualify the HTTP response code. A few request validation errors send an HTTP status code as an integer here instead, for example `422`.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (any, required)
    A string indicating the kind of error, used to further qualify the HTTP response code. A few request validation errors send an HTTP status code as an integer here instead, for example `422`.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid