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

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

<ParamField header="encrypted_key" type="string">
  Use your own Twilio account and only return inbound numbers associated with that account sid (optional).

  Learn more about BYOT [here](/tutorials/custom-twilio).
</ParamField>

### Query Parameters

<ParamField query="from_number" type="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.
</ParamField>

<ParamField query="to_number" type="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.
</ParamField>

<ParamField query="from" type="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.
</ParamField>

<ParamField query="to" type="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.
</ParamField>

<ParamField query="limit" type="int" default="1000">
  The maximum number of calls to return in the response.
</ParamField>

<ParamField query="ascending" type="boolean" default="false">
  Whether to sort the calls in ascending order of their creation time.
</ParamField>

<ParamField query="sort_by" type="string" default="created_at">
  Field to sort the results by. Available options are `created_at` (default) and `updated_at`.
</ParamField>

<ParamField query="start_date" type="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.
</ParamField>

<ParamField query="end_date" type="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.
</ParamField>

<ParamField query="created_at" type="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.
</ParamField>

<ParamField query="timezone" type="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.
</ParamField>

<ParamField query="update_start_date" type="string">
  Get calls updated including and after a specific date.
  Format: YYYY-MM-DD
</ParamField>

<ParamField query="update_end_date" type="string">
  Get calls updated including and before a specific date.
  Format: YYYY-MM-DD
</ParamField>

<ParamField query="completed" type="boolean">
  Whether to filter calls by complete status.
</ParamField>

<ParamField query="batch_id" type="string">
  Get calls from a specific batch.
</ParamField>

<ParamField query="answered_by" type="string">
  Filter by answered\_by type.
  Example: human
</ParamField>

<ParamField query="inbound" type="boolean">
  Whether to filter based on inbound or not.
</ParamField>

<ParamField query="duration_gt" type="float">
  Duration (Call Length) greater than the value provided.
  Example: 0.5 (This would be equal to half a minute)
</ParamField>

<ParamField query="duration_lt" type="float">
  Duration (Call Length) less than the value provided.
  Example: 0.5 (This would be equal to half a minute)
</ParamField>

<ParamField query="campaign_id" type="string">
  Get calls for a specific campaign id.
</ParamField>

### Response

<ResponseField name="total_count" type="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.
</ResponseField>

<ResponseField name="count" type="integer">
  The number of calls returned in the response.
</ResponseField>

<ResponseField name="calls" type="array">
  An array of call data objects. See the [Call](/api-v1/get/calls-id) section for details.

  Note: Individual call transcripts are not included due to their size.
</ResponseField>

<ResponseExample>
  ```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
      ]
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)