Call Details

curl --request GET \
  --url https://api.bland.ai/v1/calls/{call_id} \
  --header 'authorization: <authorization>'

const options = {method: 'GET', headers: {authorization: '<authorization>'}};

fetch('https://api.bland.ai/v1/calls/{call_id}', 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/{call_id}",
  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/{call_id}"

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

}

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/calls/{call_id}")

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

{
    "call_id": "12345678-1234-1234-1234-123456789012",
    "call_length": 0.75,
    "batch_id": null,
    "to": "+12223334444",
    "from": "+17163511654",
    "request_data": {
        "phone_number": "+12223334444",
        "wait": true,
        "language": "ENG"
    },
    "completed": true,
    "created_at": "2024-04-27T23:51:18.025251+00:00",
    "inbound": false,
    "queue_status": "completed",
    "endpoint_url": "api.prod.bland.ai",
    "max_duration": 30,
    "error_message": null,
    "variables": {
        "now": "Sat Apr 27 2024 18:51:25 GMT-0500 (Central Daylight Time)",
        "now_utc": "Sat, 27 Apr 2024 23:51:25 GMT",
        "short_from": "7163511654",
        "short_to": "2223334444",
        "from": "+17163511654",
        "to": "+12223334444",
        "call_id": "12345678-1234-1234-1234-123456789012",
        "phone_number": "+12223334444",
        "city": "SAN FRANCISCO",
        "country": "US",
        "state": "CA",
        "zip": "12345",
        "input": {
            "date": "2024-04-28",
            "rooms": 3
        }
    },
    "answered_by": "human",
    "record": false,
    "recording_url": null,
    "c_id": "12345678-1234-1234-1234-123456789012",
    "metadata": {},
    "summary": "The call was a conversation between a hotel booking service assistant and a customer. The customer expressed interest in booking a hotel room for tomorrow and needing three rooms. The assistant booked book the reservation for three rooms for the next day. Then, the call ended with the assistant thanking the customer for choosing their service.",
    "price": 0.068,
    "started_at": "2024-04-27T23:51:25+00:00",
    "local_dialing": false,
    "call_ended_by": "ASSISTANT",
    "pathway_id": "b1693602-c05e-4b5c-b187-d0189a42aebf",
    "pathway_logs": null,
    "pathway_version": 1,
    "analysis": null,
    "concatenated_transcript": "user: Hello? \n assistant: Hi there! I'm calling from the hotel booking service. I'd love to help you with your reservation. Could you let me know what day you'd like to book your hotel for and how many rooms you'll need? \n user: Hopefully, tomorrow, I'm thinking. ...",
    "transcripts": [
        {
            "id": 7395694,
            "created_at": "2024-04-27T23:51:28.568385+00:00",
            "text": "Hello?",
            "user": "user",
            "c_id": "12345678-1234-1234-1234-123456789012",
            "status": null,
            "transcript_id": null
        },
        {
            "id": 7395698,
            "created_at": "2024-04-27T23:51:30.689815+00:00",
            "text": "Hi there! I'm calling from the hotel booking service. I'd love to help you with your reservation. Could you let me know what day you'd like to book your hotel for and how many rooms you'll need?",
            "user": "assistant",
            "c_id": "12345678-1234-1234-1234-123456789012",
            "status": null,
            "transcript_id": "12345678-1234-1234-1234-123456789014"
        },
        //...
    ],
    "status": "completed",
    "corrected_duration": "45",
    "end_at": "2024-04-27T23:52:10.000Z",
    "voice_id": "745fbef5-f445-44fa-91ba-93f89803e1ce",
    "warm_transfer_call": {
        "proxy_agent_calls": [
            {
                "state": "MERGED",
                "call_id": "12345678-1234-1234-1234-123456789013",
                "phone_number": "+14158589038"
            }
        ],
        "state": "MERGED"
    },
    "is_proxy_agent_call": false,
    "is_canary": false
}

GET

calls

{call_id}

Call Details

curl --request GET \
  --url https://api.bland.ai/v1/calls/{call_id} \
  --header 'authorization: <authorization>'

const options = {method: 'GET', headers: {authorization: '<authorization>'}};

fetch('https://api.bland.ai/v1/calls/{call_id}', 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/{call_id}",
  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/{call_id}"

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

}

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/calls/{call_id}")

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

{
    "call_id": "12345678-1234-1234-1234-123456789012",
    "call_length": 0.75,
    "batch_id": null,
    "to": "+12223334444",
    "from": "+17163511654",
    "request_data": {
        "phone_number": "+12223334444",
        "wait": true,
        "language": "ENG"
    },
    "completed": true,
    "created_at": "2024-04-27T23:51:18.025251+00:00",
    "inbound": false,
    "queue_status": "completed",
    "endpoint_url": "api.prod.bland.ai",
    "max_duration": 30,
    "error_message": null,
    "variables": {
        "now": "Sat Apr 27 2024 18:51:25 GMT-0500 (Central Daylight Time)",
        "now_utc": "Sat, 27 Apr 2024 23:51:25 GMT",
        "short_from": "7163511654",
        "short_to": "2223334444",
        "from": "+17163511654",
        "to": "+12223334444",
        "call_id": "12345678-1234-1234-1234-123456789012",
        "phone_number": "+12223334444",
        "city": "SAN FRANCISCO",
        "country": "US",
        "state": "CA",
        "zip": "12345",
        "input": {
            "date": "2024-04-28",
            "rooms": 3
        }
    },
    "answered_by": "human",
    "record": false,
    "recording_url": null,
    "c_id": "12345678-1234-1234-1234-123456789012",
    "metadata": {},
    "summary": "The call was a conversation between a hotel booking service assistant and a customer. The customer expressed interest in booking a hotel room for tomorrow and needing three rooms. The assistant booked book the reservation for three rooms for the next day. Then, the call ended with the assistant thanking the customer for choosing their service.",
    "price": 0.068,
    "started_at": "2024-04-27T23:51:25+00:00",
    "local_dialing": false,
    "call_ended_by": "ASSISTANT",
    "pathway_id": "b1693602-c05e-4b5c-b187-d0189a42aebf",
    "pathway_logs": null,
    "pathway_version": 1,
    "analysis": null,
    "concatenated_transcript": "user: Hello? \n assistant: Hi there! I'm calling from the hotel booking service. I'd love to help you with your reservation. Could you let me know what day you'd like to book your hotel for and how many rooms you'll need? \n user: Hopefully, tomorrow, I'm thinking. ...",
    "transcripts": [
        {
            "id": 7395694,
            "created_at": "2024-04-27T23:51:28.568385+00:00",
            "text": "Hello?",
            "user": "user",
            "c_id": "12345678-1234-1234-1234-123456789012",
            "status": null,
            "transcript_id": null
        },
        {
            "id": 7395698,
            "created_at": "2024-04-27T23:51:30.689815+00:00",
            "text": "Hi there! I'm calling from the hotel booking service. I'd love to help you with your reservation. Could you let me know what day you'd like to book your hotel for and how many rooms you'll need?",
            "user": "assistant",
            "c_id": "12345678-1234-1234-1234-123456789012",
            "status": null,
            "transcript_id": "12345678-1234-1234-1234-123456789014"
        },
        //...
    ],
    "status": "completed",
    "corrected_duration": "45",
    "end_at": "2024-04-27T23:52:10.000Z",
    "voice_id": "745fbef5-f445-44fa-91ba-93f89803e1ce",
    "warm_transfer_call": {
        "proxy_agent_calls": [
            {
                "state": "MERGED",
                "call_id": "12345678-1234-1234-1234-123456789013",
                "phone_number": "+14158589038"
            }
        ],
        "state": "MERGED"
    },
    "is_proxy_agent_call": false,
    "is_canary": false
}

Headers

string

required

Your API key for authentication.

string

Use your own Twilio account and only return inbound numbers associated with that account sid (optional).Learn more about BYOT here.

Path Parameters

string

required

The unique identifier of the call for which you want to retrieve detailed information.

Response

array of objects

An array of phrases spoken during the call.Each index includes:

id
created_at
text
user (can be user, assistant, robot, or agent-action)

number

The unique identifier for the call.

number

The length of the call in minutes.

string

Number that the person was transferred to.

string

The timestamp when the call was transferred to another number.

string

If the call is part of a batch, it’s batch_id will be here.

string

The phone number that received the call.

string

The phone number that made the call.

object

Details about parameters in the original api request.

boolean

Whether the call has been completed. If it differs from the value of ‘queue_status’, this will be the most up-to-date status.

boolean

Whether the call was inbound or outbound. Will be false for outbound calls.

string

The timestamp for when the call request was created.

string

The time the call was connected.

string

The time that the call will automatically be ended at if it’s still connected (because of max_duration).

string

The status of the call. During extremely high volume periods, calls may be queued for a short period of time before being dispatched.

Statuses:

Progresses through the following stages:

new: An API request has been received.
queued: Call pararameters have been validated and authentication succeeded.
allocated: Extremely brief, the call is being dispatched.
started: The phone call is live and in progress.
complete: The phone call has ended successfully.

The following statuses show the point that was reached before an error:

pre_queue_error: An error occurred before the call was queued. Invalid parameters generally cause this.
queue_error: Error occurred while the call was queued. Ex. Valid phone number but to an unserviced area.
call_error: Error occurred during live call. May be caused by transferring to an invalid phone number or an unforeseen error.
complete_error: Error occurred after the call was completed. Ex. A post-call webhook failed.

If at any point an error occurs, it will be recorded in the error_message field.

string

The url of the deployment that the call was handled on. Will always be “api.prod.bland.ai” unless the call was handled on a custom Enterprise deployment.

number

The maximum length of time the call was allowed to last. If the call would exceed this length, it’s ended early.

string

If an error occurs, this will contain a description of the error. Otherwise, it will be null.

object

Variables created during the call - both system variables as well as generated with dynamic_data or Custom Tools.For example, if you used a dynamic_data API request to generate a variable called appointment_time, you would see it here (both the agent’s inputs and the response variables).

string

This field contains one of the following values:

human: The call was answered by a human.
voicemail: The call was answered by an answering machine or voicemail.
unknown: There was not enough audio at the start of the call to make a determination.
no-answer: The call was not answered.
null: Not enabled, or still processing the result.

Webhooks may take up to a minute to fire after the call ends while the call audio is processed.

Notes:

Determinations are based on audio from the first five seconds of the phone call.
unknown is most likely a human, especially if there are multiple transcripts.
Optimize calls for accurate results by getting humans to respond in the first five seconds:
- Use with wait_for_greeting
- Use a short greeting in first_sentence such as “Hello?” or “Hi, is this {{name}}?”

boolean

Whether the call audio was recorded.

string

The URL of the recording of the call. Only available if record was set to true in the original API request.

object

Metadata about the call. This can include information about the client, customer, or any other data you want to include.This is identical to the metadata that was set in the original API request to send the call.

string

A short summary of the call based off of the transcript that’s generated when the call ends.

number

The cost of the call in USD.

boolean

Whether Local Dialing was enabled for your account at the time of the call.

string

Whether the call was ended by Bland’s system or the other end of the line.

ASSISTANT: The agent ended the call.
USER: The user ended the call.

string

The unique identifier for a conversational pathway.

string

Pathways calls will have extra logs here that have much more detailed information about the chosen nodes and internal reasoning throughout the flow.

number

The version number of the pathway used for this call, if the call used a pathway. Returns null if no pathway was used for the call.

object

The structured data extracted from the call during post-call analysis.

string

A single string containing all of the text from the call. Excludes system messages and auto-generated data.

array of objects

An array of phrases spoken during the call.Each index includes:

id
created_at
text
user (can be user, assistant, robot, or agent-action)

string

The status of the call. This is the most up-to-date status of the call, but is only present for calls that have been successfully created.

Call Status Values

Possible status values:

completed - Call was successfully completed, this can be both human or voicemail answered (see answered_by for details on who the call was answered by)
failed - Call failed to connect or complete (see error_message for details)
busy - Called number was busy
no-answer - Call was not answered
canceled - Call was canceled before completion
unknown - Status could not be determined

Common failure reasons and troubleshooting:When status is failed, check the error_message field for specific details:

“The number you dialed is not found.”
- The phone number is invalid or not in service
- Verify the phone number format and that it’s currently active
“The number you dialed is temporarily unavailable.”
- Network issues or temporary service disruption
- Retry the call after a short delay
“The number you dialed is busy. Please try again later.”
- Called party is on another call without call waiting
- Try calling at a different time
“Service Provider Blocked Call due to Spam or Number Reputation. Try a different number.”
- Call blocked by carrier due to spam filtering
- Use a different from number or contact your carrier

string

The corrected duration of the call in seconds. This is the actual length of the call, not the max_duration.

array of objects

Citations extracted from the transcript if a citation schema was attached to the call.You can build a citation schema here.

Note: Citation schemas are very powerful and accurate, but also are more resource intensive to run. As such, for the time being, they are an enterprise-only feature.

object

Information about warm transfer calls if the call was part of a warm transfer. Contains details about proxy agent calls and transfer state.

Show Structure

proxy_agent_calls: Array of proxy agent call objects, each containing:
- state: The state of the proxy agent call (STARTED, TIMED_OUT, CANCELLED, MERGED, NO_ANSWER)
- call_id: The unique identifier of the proxy agent call
- phone_number: The phone number used for the proxy agent call
state: The overall state of the warm transfer (STARTED, TIMED_OUT, CANCELLED, MERGED, NO_ANSWER)

boolean

Whether this call is a proxy agent call (part of a warm transfer process). Returns true if this call was created as part of a warm transfer to connect with an agent, false otherwise.

boolean

Whether the call ran through a canary deployment. Returns true if the call was routed through a canary deployment, false for production, and null if the deployment could not be determined. Use this to programmatically distinguish canary traffic from production when ingesting call data.

string

The unique identifier of the voice used by the agent during the call.

{
    "call_id": "12345678-1234-1234-1234-123456789012",
    "call_length": 0.75,
    "batch_id": null,
    "to": "+12223334444",
    "from": "+17163511654",
    "request_data": {
        "phone_number": "+12223334444",
        "wait": true,
        "language": "ENG"
    },
    "completed": true,
    "created_at": "2024-04-27T23:51:18.025251+00:00",
    "inbound": false,
    "queue_status": "completed",
    "endpoint_url": "api.prod.bland.ai",
    "max_duration": 30,
    "error_message": null,
    "variables": {
        "now": "Sat Apr 27 2024 18:51:25 GMT-0500 (Central Daylight Time)",
        "now_utc": "Sat, 27 Apr 2024 23:51:25 GMT",
        "short_from": "7163511654",
        "short_to": "2223334444",
        "from": "+17163511654",
        "to": "+12223334444",
        "call_id": "12345678-1234-1234-1234-123456789012",
        "phone_number": "+12223334444",
        "city": "SAN FRANCISCO",
        "country": "US",
        "state": "CA",
        "zip": "12345",
        "input": {
            "date": "2024-04-28",
            "rooms": 3
        }
    },
    "answered_by": "human",
    "record": false,
    "recording_url": null,
    "c_id": "12345678-1234-1234-1234-123456789012",
    "metadata": {},
    "summary": "The call was a conversation between a hotel booking service assistant and a customer. The customer expressed interest in booking a hotel room for tomorrow and needing three rooms. The assistant booked book the reservation for three rooms for the next day. Then, the call ended with the assistant thanking the customer for choosing their service.",
    "price": 0.068,
    "started_at": "2024-04-27T23:51:25+00:00",
    "local_dialing": false,
    "call_ended_by": "ASSISTANT",
    "pathway_id": "b1693602-c05e-4b5c-b187-d0189a42aebf",
    "pathway_logs": null,
    "pathway_version": 1,
    "analysis": null,
    "concatenated_transcript": "user: Hello? \n assistant: Hi there! I'm calling from the hotel booking service. I'd love to help you with your reservation. Could you let me know what day you'd like to book your hotel for and how many rooms you'll need? \n user: Hopefully, tomorrow, I'm thinking. ...",
    "transcripts": [
        {
            "id": 7395694,
            "created_at": "2024-04-27T23:51:28.568385+00:00",
            "text": "Hello?",
            "user": "user",
            "c_id": "12345678-1234-1234-1234-123456789012",
            "status": null,
            "transcript_id": null
        },
        {
            "id": 7395698,
            "created_at": "2024-04-27T23:51:30.689815+00:00",
            "text": "Hi there! I'm calling from the hotel booking service. I'd love to help you with your reservation. Could you let me know what day you'd like to book your hotel for and how many rooms you'll need?",
            "user": "assistant",
            "c_id": "12345678-1234-1234-1234-123456789012",
            "status": null,
            "transcript_id": "12345678-1234-1234-1234-123456789014"
        },
        //...
    ],
    "status": "completed",
    "corrected_duration": "45",
    "end_at": "2024-04-27T23:52:10.000Z",
    "voice_id": "745fbef5-f445-44fa-91ba-93f89803e1ce",
    "warm_transfer_call": {
        "proxy_agent_calls": [
            {
                "state": "MERGED",
                "call_id": "12345678-1234-1234-1234-123456789013",
                "phone_number": "+14158589038"
            }
        ],
        "state": "MERGED"
    },
    "is_proxy_agent_call": false,
    "is_canary": false
}

Docs for agents: llms.txt

⌘I

Basic Tutorials

Calls

Conversational Pathways

Knowledge Bases

Numbers

Blocked Numbers

Widgets

Tools

Contacts

Memory

Node tests

Agent Testing

Evals

Guard Rails

Web Agents

Live Translation

Custom Twilio Accounts

Batches

Prompts

Account

Organizations

Messaging

SIP Trunks

Custom Dialing Pools

Personas

Citation Schemas

Alarms

Triage

Call Details

Headers

Path Parameters

Response

​Headers

​Path Parameters

​Response

Headers

Path Parameters

Response