Retell AI List Calls API
The List Calls API from Retell AI — 2 operation(s) for list calls.
OpenAPI Specification
openapi: 3.0.3
info:
title: Retell SDK Add Community Voice List Calls API
version: 3.0.0
contact:
name: Retell Support
url: https://www.retellai.com/
email: support@retellai.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
description: The production server.
security:
- api_key: []
tags:
- name: List Calls
paths:
/v2/list-calls:
post:
description: Retrieve call details
operationId: listCalls
deprecated: true
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
filter_criteria:
type: object
description: Filter criteria for the calls to retrieve.
example:
call_id:
- call_5a82f0a43ea0977566b1104fcfc
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
metadata.customer_id:
- cust_123
dynamic_variables.user_name:
- John
properties:
call_id:
type: array
items:
type: string
minLength: 1
description: Only retrieve calls with specific call id(s).
agent_id:
type: array
items:
type: string
minLength: 1
description: Only retrieve calls that are made with specific agent(s).
version:
type: array
items:
type: integer
description: The version of the agent to use for the call.
call_status:
type: array
items:
type: string
enum:
- not_connected
- ongoing
- ended
- error
description: Only retrieve calls with specific call status(es).
in_voicemail:
type: array
items:
type: boolean
description: Only retrieve calls that are in voicemail or not in voicemail.
disconnection_reason:
type: array
items:
$ref: '#/components/schemas/DisconnectionReason'
description: Only retrieve calls with specific disconnection reason(s).
from_number:
type: array
items:
type: string
minLength: 1
description: Only retrieve calls with specific from number(s).
to_number:
type: array
items:
type: string
minLength: 1
description: Only retrieve calls with specific to number(s).
batch_call_id:
type: array
items:
type: string
description: Only retrieve calls with specific batch call id(s).
call_type:
type: array
items:
type: string
enum:
- web_call
- phone_call
description: Only retrieve calls with specific call type(s).
direction:
type: array
items:
type: string
enum:
- inbound
- outbound
description: Only retrieve calls with specific direction(s).
user_sentiment:
type: array
items:
type: string
enum:
- Negative
- Positive
- Neutral
- Unknown
description: Only retrieve calls with specific user sentiment(s).
call_successful:
type: array
items:
type: boolean
description: Only retrieve calls with specific call successful(s).
start_timestamp:
type: object
properties:
upper_threshold:
type: integer
lower_threshold:
type: integer
description: Only retrieve calls with specific range of start timestamp(s).
end_timestamp:
type: object
properties:
upper_threshold:
type: integer
lower_threshold:
type: integer
description: Only retrieve calls with specific range of end timestamp(s).
duration_ms:
type: object
properties:
upper_threshold:
type: integer
lower_threshold:
type: integer
description: Only retrieve calls with specific range of duration(s).
e2e_latency_p50:
type: object
properties:
upper_threshold:
type: integer
lower_threshold:
type: integer
metadata:
type: object
description: 'Filter by metadata fields using dot notation (e.g., `metadata.customer_id`).
Values are matched exactly as strings.
'
additionalProperties:
type: array
items:
type: string
example:
metadata.customer_id:
- cust_123
dynamic_variables:
type: object
description: 'Filter by dynamic variables using dot notation (e.g., `dynamic_variables.name`).
Values are matched exactly as strings.
'
additionalProperties:
type: array
items:
type: string
example:
dynamic_variables.user_name:
- John
sort_order:
type: string
enum:
- ascending
- descending
default: descending
description: The calls will be sorted by `start_timestamp`, whether to return the calls in ascending or descending order.
limit:
type: integer
default: 50
description: 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:
type: string
description: 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.
responses:
'200':
description: Successfully retrieved calls.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/V2CallResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- List Calls
/v3/list-calls:
post:
description: List calls with unified cursor pagination response.
operationId: listCallsV3
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
filter_criteria:
$ref: '#/components/schemas/CallFilter'
sort_order:
type: string
enum:
- ascending
- descending
default: descending
description: Sort calls by `start_timestamp` in ascending or descending order.
limit:
type: integer
default: 50
maximum: 1000
description: Maximum number of calls to return.
skip:
type: integer
minimum: 0
default: 0
description: Number of records to skip for pagination.
pagination_key:
type: string
description: Opaque pagination cursor from a previous response.
not:
required:
- skip
- pagination_key
responses:
'200':
description: Successfully retrieved calls.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponseBase'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/V3CallResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- List Calls
components:
schemas:
CallLatency:
type: object
properties:
p50:
type: number
description: 50 percentile of latency, measured in milliseconds.
example: 800
p90:
type: number
description: 90 percentile of latency, measured in milliseconds.
example: 1200
p95:
type: number
description: 95 percentile of latency, measured in milliseconds.
example: 1500
p99:
type: number
description: 99 percentile of latency, measured in milliseconds.
example: 2500
max:
type: number
description: Maximum latency in the call, measured in milliseconds.
example: 2700
min:
type: number
description: Minimum latency in the call, measured in milliseconds.
example: 500
num:
type: number
description: Number of data points (number of times latency is tracked).
example: 10
values:
type: array
items:
type: number
description: All the latency data points in the call, measured in milliseconds.
ToolCallResultUtterance:
type: object
required:
- role
- tool_call_id
- content
properties:
role:
type: string
enum:
- tool_call_result
description: This is the result of a tool call.
tool_call_id:
type: string
description: Tool call id, globally unique.
content:
type: string
description: Result of the tool call, can be a string, a stringified json, etc.
successful:
type: boolean
description: Whether the tool call was successful.
PaginatedResponseBase:
type: object
properties:
pagination_key:
type: string
description: Pagination key for the next page.
has_more:
type: boolean
description: Whether more results are available.
CallAnalysis:
type: object
properties:
call_summary:
type: string
example: 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.
description: A high level summary of the call.
in_voicemail:
type: boolean
example: false
description: Whether the call is entered voicemail.
user_sentiment:
type: string
enum:
- Negative
- Positive
- Neutral
- Unknown
example: Positive
description: Sentiment of the user in the call.
call_successful:
type: boolean
example: true
description: Whether the agent seems to have a successful call with the user, where the agent finishes the task, and the call was complete without being cutoff.
custom_analysis_data:
type: object
description: Custom analysis data that was extracted based on the schema defined in agent post call analysis data. Can be empty if nothing is specified.
UtteranceOrToolCall:
oneOf:
- $ref: '#/components/schemas/Utterance'
- $ref: '#/components/schemas/ToolCallInvocationUtterance'
- $ref: '#/components/schemas/ToolCallResultUtterance'
- $ref: '#/components/schemas/NodeTransitionUtterance'
- $ref: '#/components/schemas/DTMFUtterance'
NumberFilter:
type: object
required:
- type
- op
- value
properties:
type:
type: string
enum:
- number
op:
type: string
enum:
- eq
- ne
- gt
- ge
- lt
- le
description: 'eq: equal, ne: not equal, gt: greater than, ge: greater than or equal, lt: less than, le: less than or equal'
value:
type: number
NodeTransitionUtterance:
type: object
required:
- role
- former_node_id
- former_node_name
- new_node_id
- new_node_name
properties:
role:
type: string
enum:
- node_transition
description: This is result of a node transition
former_node_id:
type: string
description: Former node id
former_node_name:
type: string
description: Former node name
new_node_id:
type: string
description: New node id
new_node_name:
type: string
description: New node name
transition_type:
type: string
enum:
- global
- global_go_back
- interrupt_go_back
- normal
description: How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition.
CustomFieldFilter:
description: A filter on a custom field, identified by key.
allOf:
- $ref: '#/components/schemas/ValueFilter'
- type: object
required:
- key
properties:
key:
type: string
description: The field name to filter on.
ValueFilter:
oneOf:
- $ref: '#/components/schemas/StringFilter'
- $ref: '#/components/schemas/NumberFilter'
- $ref: '#/components/schemas/BooleanFilter'
- $ref: '#/components/schemas/RangeFilter'
- $ref: '#/components/schemas/EnumFilter'
- $ref: '#/components/schemas/PresentFilter'
AgentFilter:
type: object
required:
- agent_id
properties:
agent_id:
type: string
minLength: 1
description: The agent ID to filter on.
version:
type: array
items:
type: number
description: Specific versions to filter on. If not provided, all versions are included.
V3CallResponse:
allOf:
- $ref: '#/components/schemas/V2CallResponse'
- type: object
description: V3 list calls response. Transcript fields are intentionally omitted.
not:
anyOf:
- required:
- transcript
- required:
- transcript_object
- required:
- transcript_with_tool_calls
- required:
- scrubbed_transcript_with_tool_calls
V2CallResponse:
oneOf:
- $ref: '#/components/schemas/V2WebCallResponse'
- $ref: '#/components/schemas/V2PhoneCallResponse'
ProductCost:
type: object
required:
- product
- cost
properties:
product:
type: string
description: Product name that has a cost associated with it.
example: elevenlabs_tts
unit_price:
type: number
description: Unit price of the product in cents per second.
example: 1
cost:
type: number
description: Cost for the product in cents for the duration of the call.
example: 60
is_transfer_leg_cost:
type: boolean
description: True if this cost item is for a transfer segment.
StringFilter:
type: object
required:
- type
- op
- value
properties:
type:
type: string
enum:
- string
op:
type: string
enum:
- eq
- ne
- sw
- ew
- co
description: 'eq: equal, ne: not equal, sw: starts with, ew: ends with, co: contains'
value:
type: string
Utterance:
type: object
required:
- role
- content
- words
properties:
role:
type: string
enum:
- agent
- user
- transfer_target
description: Documents whether this utterance is spoken by agent or user.
example: agent
content:
type: string
description: Transcript of the utterances.
example: hi how are you doing?
words:
type: array
example:
- word: hi
start: 0.7
end: 1.3
description: 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.
items:
type: object
properties:
word:
type: string
description: Word transcript (with punctuation if applicable).
start:
type: number
description: Start time of the word in the call in second. This is relative audio time, not wall time.
end:
type: number
description: End time of the word in the call in second. This is relative audio time, not wall time.
ToolCallFilter:
type: object
required:
- name
properties:
name:
type: string
description: The tool call name to filter on.
latency_ms:
oneOf:
- $ref: '#/components/schemas/NumberFilter'
- $ref: '#/components/schemas/RangeFilter'
description: Filter by tool call latency in milliseconds.
success:
$ref: '#/components/schemas/BooleanFilter'
description: Filter by tool call success status.
RangeFilter:
type: object
required:
- type
- op
- value
properties:
type:
type: string
enum:
- range
op:
type: string
enum:
- bt
description: 'bt: between'
value:
type: array
minItems: 2
maxItems: 2
items:
type: number
description: '[lower_bound, upper_bound]'
V2WebCallResponse:
allOf:
- type: object
required:
- call_type
- access_token
properties:
call_type:
type: string
enum:
- web_call
example: web_call
description: Type of the call. Used to distinguish between web call and phone call.
access_token:
type: string
example: eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p
description: Access token to enter the web call room. This needs to be passed to your frontend to join the call.
- $ref: '#/components/schemas/V2CallBase'
V2CallBase:
type: object
required:
- call_id
- agent_id
- agent_version
- call_status
properties:
call_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the call. Used to identify the call in the LLM websocket and used to authenticate in the audio websocket.
agent_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: Corresponding agent id of this call.
agent_name:
type: string
example: My Agent
description: Name of the agent.
agent_version:
type: integer
example: 1
description: The version of the agent.
call_status:
type: string
enum:
- registered
- not_connected
- ongoing
- ended
- error
example: registered
description: '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 hung up, or call transferred.
- `error`: Call encountered error.
'
metadata:
type: object
description: 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:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description: Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.
collected_dynamic_variables:
type: object
additionalProperties: {}
example:
last_node_name: Test node
description: Dynamic variables collected from the call. Only available after the call ends.
custom_sip_headers:
type: object
additionalProperties:
type: string
description: Custom SIP headers to be added to the call.
example:
X-Custom-Header: Custom Value
data_storage_setting:
type: string
enum:
- everything
- everything_except_pii
- basic_attributes_only
example: everything
description: Data storage setting for this call's agent. "everything" stores all data, "everything_except_pii" excludes PII when possible, "basic_attributes_only" stores only metadata.
nullable: true
opt_in_signed_url:
type: boolean
example: true
description: Whether this agent opts in for signed URLs for public logs and recordings. When enabled, the generated URLs will include security signatures that restrict access and automatically expire after 24 hours.
start_timestamp:
type: integer
example: 1703302407333
description: Begin timestamp (milliseconds since epoch) of the call. Available after call starts.
end_timestamp:
type: integer
example: 1703302428855
description: End timestamp (milliseconds since epoch) of the call. Available after call ends.
transfer_end_timestamp:
type: integer
example: 1703302628855
description: Transfer end timestamp (milliseconds since epoch) of the call. Available after transfer call ends.
duration_ms:
type: integer
example: 10000
description: Duration of the call in milliseconds. Available after call ends.
transcript:
type: string
example: 'Agent: hi how are you doing?
User: Doing pretty well. How are you?
Agent: That''s great to hear! I''m doing well too, thanks! What''s up?
User: I don''t have anything in particular.
Agent: Got it, just checking in!
User: Alright. See you.
Agent: have a nice day
'
description: Transcription of the call. Available after call ends.
transcript_object:
type: array
items:
$ref: '#/components/schemas/Utterance'
description: Transcript of the call in the format of a list of utterance, with timestamp. Available after call ends.
transcript_with_tool_calls:
type: array
items:
$ref: '#/components/schemas/UtteranceOrToolCall'
description: 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.
scrubbed_transcript_with_tool_calls:
type: array
items:
$ref: '#/components/schemas/UtteranceOrToolCall'
description: Transcript of the call weaved with tool call invocation and results, without PII. It precisely captures when (at what utterance, which word) the tool was invoked and what was the result. Available after call ends.
recording_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav
description: Recording of the call. Available after call ends.
recording_multi_channel_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav
description: Recording of the call, with each party's audio stored in a separate channel. Available after the call ends.
scrubbed_recording_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav
description: Recording of the call without PII. Available after call ends.
scrubbed_recording_multi_channel_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav
description: Recording of the call without PII, with each party's audio stored in a separate channel. Available after the call ends.
public_log_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt
description: 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.
knowledge_base_retrieved_contents_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt
description: URL to the knowledge base retrieved contents of the call. Available after call ends if the call utilizes knowledge base feature. It consists of the respond id and the retrieved contents related to that response. It's already rendered in call history tab of dashboard, and you can also manually download and check against the transcript to view the knowledge base retrieval results.
latency:
type: object
description: 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.
properties:
e2e:
description: 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.
$ref: '#/components/schemas/CallLatency'
asr:
description: Transcription latency (diff between the duration of the chunks streamed and the durations of the transcribed part) tracking of the call.
$ref: '#/components/schemas/CallLatency'
llm:
description: 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.
$ref: '#/components/schemas/CallLatency'
llm_websocket_network_rtt:
description: LLM websocket roundtrip latency (between user server and Retell server) tracking of the call. Only populated for calls using custom LLM.
$ref: '#/components/schemas/CallLatency'
tts:
description: Text-to-speech latency (from the triggering of TTS to first byte received) tracking of the call.
$ref: '#/components/schemas/CallLatency'
knowledge_base:
description: 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.
$ref: '#/components/schemas/CallLatency'
s2s:
description: 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.
$ref: '#/components/schemas/CallLatency'
disconnection_reason:
$ref: '#/components/schemas/DisconnectionReason'
example: agent_hangup
description: The reason for the disconnection of the call. Read detailed description about reasons listed here at [Disconnection Reason Doc](/reliability/debug-call-disconnect#understanding-disconnection-reasons).
transfer_destination:
type: string
example: '+12137771234'
description: The destination number or identifier where the call was transferred to. Only populated when the disconnection reason was `call_transfer`. Can be a phone number or a SIP URI. SIP URIs are prefixed with "sip:" and may include a ";transport=..." portion (if transport is known) where the transport type can be "tls", "tcp" or "udp".
nullable: true
call_analysis:
description: Post call analysis that includes information such as sentiment, status, summary, and custom defined data to extract. Available after
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/retell-ai/refs/heads/main/openapi/retell-ai-list-calls-api-openapi.yml