GET
/
v1
/
calls
List 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).Learn more about BYOT here.

​
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. 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
    ]
}