# List all calls

Retrieve a paginated list of calls.
Requires the `read_conversations` OAuth scope.

Endpoint: GET /calls
Version: Preview
Security: bearerAuth

## Query parameters:

  - `page` (integer)
    The page of results to fetch. Defaults to first page

  - `per_page` (integer)
    How many results to display per page. Defaults to 25. Must be between 1 and 25. A value outside that range returns a 400 error.

## Header parameters:

  - `Intercom-Version` (string)

## Response 200 fields (application/json):

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

  - `data` (array)
    A list of calls.

  - `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 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

  - `total_count` (integer)
    Total number of items available.
    Example: 0

  - `pages` (object)
    The majority of list resources in the API are paginated to allow clients to traverse data over multiple requests.

Their responses are likely to contain a pages object that hosts pagination links which a client can use to paginate through the data without having to construct a query. The link relations for the pages field are as follows.

  - `pages.type` (string)
    Enum: "pages"

  - `pages.page` (integer)
    Example: 1

  - `pages.next` (string)
    A link to the next page of results. Omitted or `null` on the last page, depending on the list. Some lists never include `next` or `prev`, so compare `page` with `total_pages` to tell whether more pages remain.

  - `pages.prev` (string)
    A link to the previous page of results. Omitted on the first page.

  - `pages.per_page` (integer)
    Example: 50

  - `pages.total_pages` (integer)
    Example: 1

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