Calls
List Calls
Returns a set of metadata for each call dispatched by your account.
GET
/
v1
/
calls
List Calls
curl --request GET \
--url https://api.bland.ai/v1/calls \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v1/calls"
headers = {"authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v1/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v1/calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v1/calls"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.bland.ai/v1/calls")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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
Use your own Twilio account and only return inbound numbers associated with that account sid (optional).Learn more about BYOT here.
Query Parameters
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.
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.
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.
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.
Field to sort the results by. Available options are
created_at (default) and updated_at.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.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.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.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.Duration (Call Length) greater than the value provided.
Example: 0.5 (This would be equal to half a minute)
Duration (Call Length) less than the value provided.
Example: 0.5 (This would be equal to half a minute)
Get calls with a specific
external_id. This is the ID you set when sending the call, or the inbound SIP header you flagged as the external ID in POST /v1/sip/attach.Response
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_countwill be 10,000. - If you have 10,000 calls and 9,000 of them match the query, the
total_countwill be 9,000 regardless of the number of calls returned in the response.
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
]
}
Docs for agents: llms.txt
Was this page helpful?
⌘I
List Calls
curl --request GET \
--url https://api.bland.ai/v1/calls \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v1/calls"
headers = {"authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v1/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v1/calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v1/calls"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.bland.ai/v1/calls")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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
]
}