GET
/
v1
/
calls
curl --request GET \
  --url https://api.bland.ai/v1/calls \
  --header 'authorization: <authorization>'
{
    "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
    ]
}

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).

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.

to
int

The ending index for the range of calls to retrieve.

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.

start_date
string

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

end_date
string

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

created_at
string

Get calls for a specific date. Can’t be used with end_date or start_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.

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 section for details.

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

{
    "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
    ]
}