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

# List Calls

> Returns a set of metadata for each call dispatched by your account.

### Headers

**authorization** `string` *required*

Your API key for authentication.

**encrypted\_key** `string`

Use your own Twilio account and only return inbound numbers associated with that account sid (optional).

Learn more about BYOT [here](https://docs.bland.ai/tutorials/custom-twilio.md).

### Query Parameters

**from\_number** `string`

Filter calls by the number they were dispatched from.

The number that initiated the call - the user's phone number for inbound calls, or the number your AI Agent called from for outbound calls.

**to\_number** `string`

Filter calls by the number they were dispatched to.

The number that answered the call - the user's phone number for outbound calls, or your AI Agent's number for inbound calls.

**from** `int`

The starting index (inclusive) for the range of calls to retrieve. For example, from=0 starts at the very first call in the result set, while from=100 starts at the 101st call.

**to** `int`

The ending index for the range of calls to retrieve. This tells the API where to stop returning data. For example, from=150 and to=200 returns 50 results, starting from the 101st result and ending just before the 151st.

**limit** `int` (default: 1000)

The maximum number of calls to return in the response.

**ascending** `boolean` (default: false)

Whether to sort the calls in ascending order of their creation time.

**sort\_by** `string` (default: created\_at)

Field to sort the results by. Available options are `created_at` (default) and `updated_at`.

**start\_date** `string`

Get calls including and after a specific date.

Accepts either a date (`YYYY-MM-DD`) or a full ISO 8601 datetime with timezone offset (e.g. `2026-02-19T00:00:00-05:00`).

When using a date-only value, dates are interpreted as UTC unless the `timezone` parameter is provided.

**end\_date** `string`

Get calls including and before a specific date.

Accepts either a date (`YYYY-MM-DD`) or a full ISO 8601 datetime with timezone offset (e.g. `2026-02-19T23:59:59-05:00`).

When using a date-only value, dates are interpreted as UTC unless the `timezone` parameter is provided.

**created\_at** `string`

Get calls for a specific date. Can't be used with `end_date` or `start_date`.

Format: `YYYY-MM-DD`. Dates are interpreted as UTC unless the `timezone` parameter is provided.

**timezone** `string`

IANA timezone name (e.g. `America/Toronto`, `America/Los_Angeles`, `UTC`).

When provided, date-only values in `start_date`, `end_date`, and `created_at` are interpreted in this timezone instead of UTC. This ensures calls are attributed to the correct local calendar day.

Has no effect on `start_date`/`end_date` values that include a timezone offset (e.g. ISO 8601 datetimes), since those already encode timezone information.

**update\_start\_date** `string`

Get calls updated including and after a specific date.
Format: YYYY-MM-DD

**update\_end\_date** `string`

Get calls updated including and before a specific date.
Format: YYYY-MM-DD

**completed** `boolean`

Whether to filter calls by complete status.

**batch\_id** `string`

Get calls from a specific batch.

**answered\_by** `string`

Filter by answered\_by type.
Example: human

**inbound** `boolean`

Whether to filter based on inbound or not.

**duration\_gt** `float`

Duration (Call Length) greater than the value provided.
Example: 0.5 (This would be equal to half a minute)

**duration\_lt** `float`

Duration (Call Length) less than the value provided.
Example: 0.5 (This would be equal to half a minute)

**campaign\_id** `string`

Get calls for a specific campaign id.

**external\_id** `string`

Get calls with a specific `external_id`. This is the ID you set when [sending the call](https://docs.bland.ai/api-v1/post/calls.md), or the inbound SIP header you flagged as the external ID in [`POST /v1/sip/attach`](https://docs.bland.ai/api-v1/post/sip-attach).

### Response

**total\_count** `integer`

The total number of calls that match the query filters. This number may be greater than the number of calls returned in the response.

For example:

* If you have 10,000 calls, and don't include any filters, the `total_count` will be 10,000.
* If you have 10,000 calls and 9,000 of them match the query, the `total_count` will be 9,000 regardless of the number of calls returned in the response.

**count** `integer`

The number of calls returned in the response.

**calls** `array`

An array of call data objects. See the [Call](https://docs.bland.ai/api-v1/get/calls-id.md) section for details.

Note: Individual call transcripts are not included due to their size.

```json Response theme={null}
{
    "count": 784,
    "calls": [
        {
            "call_id": "c1234567-89ab-cdef-0123-456789abcdef",
            "created_at": "2023-12-21T23:25:14.801193+00:00",
            "call_length": 0.834, // minutes
            "to": "5551234567",
            "from": "+15551234567",
            "completed": true,
            "queue_status": "complete",
            "error_message": null,
            "answered_by": "human",
            "batch_id": "b1234567-89ab-cdef-0123-gen-batch",
        },
        //... Additional call objects
    ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


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