List Calls

POST

list-calls

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

async function main() {
  const callResponses = await client.call.list();

  console.log(callResponses);
}

main();

[
  {
    "call_type": "web_call",
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p",
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
    "call_status": "registered",
    "metadata": {},
    "retell_llm_dynamic_variables": {
      "customer_name": "John Doe"
    },
    "opt_out_sensitive_data_storage": true,
    "start_timestamp": 1703302407333,
    "end_timestamp": 1703302428855,
    "transcript": "Agent: hi how are you doing?\nUser: Doing pretty well. How are you?\nAgent: That's great to hear! I'm doing well too, thanks! What's up?\nUser: I don't have anything in particular.\nAgent: Got it, just checking in!\nUser: Alright. See you.\nAgent: have a nice day\n ",
    "transcript_object": [
      {
        "role": "agent",
        "content": "hi how are you doing?",
        "words": [
          {
            "word": "hi",
            "start": 0.7,
            "end": 1.3
          }
        ]
      }
    ],
    "transcript_with_tool_calls": [
      {
        "role": "agent",
        "content": "hi how are you doing?",
        "words": [
          {
            "word": "hi",
            "start": 0.7,
            "end": 1.3
          }
        ]
      }
    ],
    "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
    "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt",
    "latency": {
      "e2e": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "llm": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "llm_websocket_network_rtt": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "tts": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "knowledge_base": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "s2s": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      }
    },
    "disconnection_reason": "agent_hangup",
    "call_analysis": {
      "call_summary": "The agent called the user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.",
      "in_voicemail": false,
      "user_sentiment": "Positive",
      "call_successful": true,
      "custom_analysis_data": {}
    },
    "call_cost": {
      "product_costs": [
        {
          "product": "elevenlabs_tts",
          "unitPrice": 1,
          "cost": 60
        }
      ],
      "total_duration_seconds": 60,
      "total_duration_unit_price": 1,
      "total_one_time_price": 10,
      "combined_cost": 70
    }
  }
]

Authorizations

Authorization

string

header

required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json

filter_criteria

object

Filter criteria for the calls to retrieve.

filter_criteria.agent_id

string[]

Only retrieve calls that are made with specific agent(s).

filter_criteria.call_status

enum<string>[]

Only retrieve calls with specific call status(es).

Available options:

registered,

ongoing,

ended,

error

filter_criteria.in_voicemail

boolean[]

Only retrieve calls that are in voicemail or not in voicemail.

filter_criteria.disconnection_reason

enum<string>[]

Only retrieve calls with specific disconnection reason(s).

Available options:

user_hangup,

agent_hangup,

call_transfer,

voicemail_reached,

inactivity,

machine_detected,

max_duration_reached,

concurrency_limit_reached,

no_valid_payment,

scam_detected,

error_inbound_webhook,

dial_busy,

dial_failed,

dial_no_answer,

error_llm_websocket_open,

error_llm_websocket_lost_connection,

error_llm_websocket_runtime,

error_llm_websocket_corrupt_payload,

error_frontend_corrupted_payload,

error_twilio,

error_no_audio_received,

error_asr,

error_retell,

error_unknown,

error_user_not_joined,

registered_call_timeout

filter_criteria.from_number

string[]

Only retrieve calls with specific from number(s).

filter_criteria.to_number

string[]

Only retrieve calls with specific to number(s).

filter_criteria.call_type

enum<string>[]

Only retrieve calls with specific call type(s).

Available options:

web_call,

phone_call

filter_criteria.direction

enum<string>[]

Only retrieve calls with specific direction(s).

Available options:

inbound,

outbound

filter_criteria.user_sentiment

enum<string>[]

Only retrieve calls with specific user sentiment(s).

Available options:

Negative,

Positive,

Neutral,

Unknown

filter_criteria.call_successful

boolean[]

Only retrieve calls with specific call successful(s).

filter_criteria.start_timestamp

object

Only retrieve calls with specific range of start timestamp(s).

filter_criteria.duration_ms

object

Only retrieve calls with specific range of duration(s).

filter_criteria.e2e_latency_p50

object

Example:

{
  "agent_id": ["agent_oBeDLoLOeuAbiuaMFXRtDOLriT12345"],
  "call_status": ["ended"],
  "call_type": ["phone_call"],
  "direction": ["inbound"],
  "user_sentiment": ["Positive"],
  "call_successful": [true],
  "start_timestamp": {
    "upper_threshold": 1738475421000,
    "lower_threshold": 1738475411000
  }
}

sort_order

enum<string>

default:

descending

The calls will be sorted by start_timestamp, whether to return the calls in ascending or descending order.

Available options:

ascending,

descending

limit

integer

default:

Limit the number of calls returned. Default 50, Max 1000. To retrieve more than 1000, use pagination_key to continue fetching the next page.

pagination_key

string

The pagination key to continue fetching the next page of calls. Pagination key is represented by a call id here, and it's exclusive (not included in the fetched calls). The last call id from the list calls is usually used as pagination key here. If not set, will start from the beginning.

Response

200

application/json

Successfully retrieved calls.

call_type

enum<string>

required

Type of the call. Used to distinguish between web call and phone call.

Available options:

web_call

Example:

"web_call"

access_token

string

required

Access token to enter the web call room. This needs to be passed to your frontend to join the call.

Example:

"eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p"

call_id

string

required

Unique id of the call. Used to identify in LLM websocket and used to authenticate in audio websocket.

Example:

"Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6"

agent_id

string

required

Corresponding agent id of this call.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

call_status

enum<string>

required

Status of call.

registered: Call id issued, starting to make a call using this id.
ongoing: Call connected and ongoing.
ended: The underlying websocket has ended for the call. Either user or agent hanged up, or call transferred.
error: Call encountered error.

Available options:

registered,

ongoing,

ended,

error

Example:

"registered"

metadata

object

An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object.

retell_llm_dynamic_variables

object

Add optional dynamic variables in key value pairs of string that injects into your Retell LLM Response Engine prompt and tool description. Only applicable for Retell LLM Response Engine.

Example:

{ "customer_name": "John Doe" }

opt_out_sensitive_data_storage

boolean

Whether this call opts out of sensitive data storage like transcript, recording, logging.

Example:

true

start_timestamp

integer

Begin timestamp (milliseconds since epoch) of the call. Available after call starts.

Example:

1703302407333

end_timestamp

integer

End timestamp (milliseconds since epoch) of the call. Available after call ends.

Example:

1703302428855

transcript

string

Transcription of the call. Available after call ends.

Example:

"Agent: hi how are you doing?\nUser: Doing pretty well. How are you?\nAgent: That's great to hear! I'm doing well too, thanks! What's up?\nUser: I don't have anything in particular.\nAgent: Got it, just checking in!\nUser: Alright. See you.\nAgent: have a nice day\n "

transcript_object

object[]

Transcript of the call in the format of a list of utterance, with timestamp. Available after call ends.

transcript_object.role

enum<string>

required

Documents whether this utterance is spoken by agent or user.

Available options:

agent,

user

Example:

"agent"

transcript_object.content

string

required

Transcript of the utterances.

Example:

"hi how are you doing?"

transcript_object.words

object[]

required

Array of words in the utterance with the word timestamp. Useful for understanding what word was spoken at what time. Note that the word timestamp is not guaranteed to be accurate, it's more like an approximation.

Example:

[{ "word": "hi", "start": 0.7, "end": 1.3 }]

transcript_with_tool_calls

object[]

Transcript of the call weaved with tool call invocation and results. It precisely captures when (at what utterance, which word) the tool was invoked and what was the result. Available after call ends.

transcript_with_tool_calls.role

enum<string>

required

Documents whether this utterance is spoken by agent or user.

Available options:

agent,

user

Example:

"agent"

transcript_with_tool_calls.content

string

required

Transcript of the utterances.

Example:

"hi how are you doing?"

transcript_with_tool_calls.words

object[]

required

Example:

[{ "word": "hi", "start": 0.7, "end": 1.3 }]

recording_url

string

Recording of the call. Available after call ends.

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav"

public_log_url

string

Public log of the call, containing details about all the requests and responses received in LLM WebSocket, latency tracking for each turntaking, helpful for debugging and tracing. Available after call ends.

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt"

latency

object

Latency tracking of the call, available after call ends. Not all fields here will be available, as it depends on the type of call and feature used.

latency.e2e

object

End to end latency (from user stops talking to agent start talking) tracking of the call. This latency does not account for the network trip time from Retell server to user frontend. The latency is tracked every time turn change between user and agent.

latency.llm

object

LLM latency (from issue of LLM call to first speakable chunk received) tracking of the call. When using custom LLM. this latency includes LLM websocket roundtrip time between user server and Retell server.

latency.llm_websocket_network_rtt

object

LLM websocket roundtrip latency (between user server and Retell server) tracking of the call. Only populated for calls using custom LLM.

latency.tts

object

Text-to-speech latency (from the triggering of TTS to first byte received) tracking of the call.

latency.knowledge_base

object

Knowledge base latency (from the triggering of knowledge base retrival to all relevant context received) tracking of the call. Only populated when using knowledge base feature for the agent of the call.

latency.s2s

object

Speech-to-speech latency (from requesting responses of a S2S model to first byte received) tracking of the call. Only populated for calls that uses S2S model like Realtime API.

disconnection_reason

enum<string>

The reason for the disconnection of the call. Read details desciption about reasons listed here at Disconnection Reason Doc.

Available options:

user_hangup,

agent_hangup,

call_transfer,

voicemail_reached,

inactivity,

machine_detected,

max_duration_reached,

concurrency_limit_reached,

no_valid_payment,

scam_detected,

error_inbound_webhook,

dial_busy,

dial_failed,

dial_no_answer,

error_llm_websocket_open,

error_llm_websocket_lost_connection,

error_llm_websocket_runtime,

error_llm_websocket_corrupt_payload,

error_frontend_corrupted_payload,

error_twilio,

error_no_audio_received,

error_asr,

error_retell,

error_unknown,

error_user_not_joined,

registered_call_timeout

Example:

"agent_hangup"

call_analysis

object

Post call analysis that includes information such as sentiment, status, summary, and custom defined data to extract. Available after call ends. Subscribe to call_analyzed webhook event type to receive it once ready.

call_cost

object

Cost of the call, including all the products and their costs and discount.

Was this page helpful?

Get Call Update Call

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

async function main() {
  const callResponses = await client.call.list();

  console.log(callResponses);
}

main();

[
  {
    "call_type": "web_call",
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p",
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
    "call_status": "registered",
    "metadata": {},
    "retell_llm_dynamic_variables": {
      "customer_name": "John Doe"
    },
    "opt_out_sensitive_data_storage": true,
    "start_timestamp": 1703302407333,
    "end_timestamp": 1703302428855,
    "transcript": "Agent: hi how are you doing?\nUser: Doing pretty well. How are you?\nAgent: That's great to hear! I'm doing well too, thanks! What's up?\nUser: I don't have anything in particular.\nAgent: Got it, just checking in!\nUser: Alright. See you.\nAgent: have a nice day\n ",
    "transcript_object": [
      {
        "role": "agent",
        "content": "hi how are you doing?",
        "words": [
          {
            "word": "hi",
            "start": 0.7,
            "end": 1.3
          }
        ]
      }
    ],
    "transcript_with_tool_calls": [
      {
        "role": "agent",
        "content": "hi how are you doing?",
        "words": [
          {
            "word": "hi",
            "start": 0.7,
            "end": 1.3
          }
        ]
      }
    ],
    "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
    "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt",
    "latency": {
      "e2e": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "llm": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "llm_websocket_network_rtt": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "tts": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "knowledge_base": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      },
      "s2s": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10,
        "values": [
          123
        ]
      }
    },
    "disconnection_reason": "agent_hangup",
    "call_analysis": {
      "call_summary": "The agent called the user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.",
      "in_voicemail": false,
      "user_sentiment": "Positive",
      "call_successful": true,
      "custom_analysis_data": {}
    },
    "call_cost": {
      "product_costs": [
        {
          "product": "elevenlabs_tts",
          "unitPrice": 1,
          "cost": 60
        }
      ],
      "total_duration_seconds": 60,
      "total_duration_unit_price": 1,
      "total_one_time_price": 10,
      "combined_cost": 70
    }
  }
]

Call (V2)

Phone Number

Agent

Single / Multi Prompt Response (Retell LLM)

Knowledge Base

Voice

Batch call

Account

Custom Telephony

Custom LLM

Authorizations

Body

Response