---
title: "PATCH /v2/update-call/{call_id}"
method: PATCH
path: "/v2/update-call/{call_id}"
---

# PATCH /v2/update-call/{call_id}

`PATCH /v2/update-call/{call_id}`

Update metadata and sensitive data storage settings for an existing call.

## Path parameters

- `call_id` string, required

## Request body

- object
  - `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. Size limited to 50kB max.
  - `data_storage_setting` 'everything' | 'everything_except_pii' | 'basic_attributes_only' — Data storage setting for this call. Overrides the agent's default setting. "everything" stores all data, "everything_except_pii" excludes PII when possible, "basic_attributes_only" stores only metadata. Cannot be downgraded from more restrictive to less restrictive settings.
  - `override_dynamic_variables` object, nullable — Override dynamic variables represented as key-value pairs of strings. Setting this will override or add the dynamic variables set in the agent during the call. Only need to set the delta where you want to override, no need to set the entire dynamic variables object. Setting this to null will remove any existing override.
  - `custom_attributes` object — Custom attributes for the call

## Response `200`

Call metadata updated successfully

- union
  - V2WebCallResponse
    - `call_type` 'web_call', required — Type of the call. Used to distinguish between web call and phone 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.
    - `call_id` string, required — Unique id of the call. Used to identify the call in the LLM websocket and used to authenticate in the audio websocket.
    - `agent_id` string, required — Corresponding agent id of this call.
    - `agent_name` string — Name of the agent.
    - `agent_version` integer, required — The version of the agent.
    - `call_status` 'registered' | 'not_connected' | 'ongoing' | 'ended' | 'error', 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 hung up, or call transferred. - `error`: Call encountered error.
    - `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 Response Engine prompt and tool description. Only applicable for Response Engine.
    - `collected_dynamic_variables` object — Dynamic variables collected from the call. Only available after the call ends.
    - `custom_sip_headers` object — Custom SIP headers to be added to the call.
    - `data_storage_setting` 'everything' | 'everything_except_pii' | 'basic_attributes_only', nullable — 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.
    - `opt_in_signed_url` boolean — 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` integer — Begin timestamp (milliseconds since epoch) of the call. Available after call starts.
    - `end_timestamp` integer — End timestamp (milliseconds since epoch) of the call. Available after call ends.
    - `transfer_end_timestamp` integer — Transfer end timestamp (milliseconds since epoch) of the call. Available after transfer call ends.
    - `duration_ms` integer — Duration of the call in milliseconds. Available after call ends.
    - `transcript` string — Transcription of the call. Available after call ends.
    - `transcript_object` Utterance[] — Transcript of the call in the format of a list of utterance, with timestamp. Available after call ends.
      - `role` 'agent' | 'user' | 'transfer_target', required — Documents whether this utterance is spoken by agent or user.
      - `content` string, required — Transcript of the utterances.
      - `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.
        - `word` string — Word transcript (with punctuation if applicable).
        - `start` number — Start time of the word in the call in second. This is relative audio time, not wall time.
        - `end` number — End time of the word in the call in second. This is relative audio time, not wall time.
    - `transcript_with_tool_calls` UtteranceOrToolCall[] — 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.
      - union
        - Utterance
          - `role` 'agent' | 'user' | 'transfer_target', required — Documents whether this utterance is spoken by agent or user.
          - `content` string, required — Transcript of the utterances.
          - `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.
            - `word` string — Word transcript (with punctuation if applicable).
            - `start` number — Start time of the word in the call in second. This is relative audio time, not wall time.
            - `end` number — End time of the word in the call in second. This is relative audio time, not wall time.
        - ToolCallInvocationUtterance
          - `role` 'tool_call_invocation', required — This is a tool call invocation.
          - `tool_call_id` string, required — Tool call id, globally unique.
          - `name` string, required — Name of the function in this tool call.
          - `arguments` string, required — Arguments for this tool call, it's a stringified JSON object.
          - `thought_signature` string — Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
        - ToolCallResultUtterance
          - `role` 'tool_call_result', required — This is the result of a tool call.
          - `tool_call_id` string, required — Tool call id, globally unique.
          - `content` string, required — Result of the tool call, can be a string, a stringified json, etc.
          - `successful` boolean — Whether the tool call was successful.
        - NodeTransitionUtterance
          - `role` 'node_transition', required — This is result of a node transition
          - `former_node_id` string, required — Former node id
          - `former_node_name` string, required — Former node name
          - `new_node_id` string, required — New node id
          - `new_node_name` string, required — New node name
          - `transition_type` 'global' | 'global_go_back' | 'interrupt_go_back' | 'normal' — 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.
        - DTMFUtterance
          - `role` 'dtmf', required — Digit pressed by the user from their phone keypad.
          - `digit` string, required — The digit pressed by the user. Will be a single digit string like "1", "2", "3", "*", "#" etc.
        - SmsUtterance
          - `role` 'sms', required — SMS message received from the user during the call (for example while the agent is leaving a voicemail). Not part of the spoken conversation.
          - `content` string, required — Text content of the SMS message.
          - `multimedia` SmsMultimediaItem[] — Multimedia attachments (MMS). Display only; not relayed into the spoken conversation.
            - `url` string, required — URL of the multimedia attachment.
            - `summary` string — Optional textual summary of the attachment.
          - `time_sec` number, required — Time the SMS was received, in seconds relative to the start of the call.
        - InjectedUtterance
          - `role` 'injected', required — External context injected into the conversation via the update-live-call API. Not spoken by either party.
          - `content` string, required — The injected context text.
          - `time_sec` number, required — Time the context was injected, in seconds relative to the start of the call.
    - `scrubbed_transcript_with_tool_calls` UtteranceOrToolCall[] — 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.
      - union
        - Utterance
          - `role` 'agent' | 'user' | 'transfer_target', required — Documents whether this utterance is spoken by agent or user.
          - `content` string, required — Transcript of the utterances.
          - `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.
            - `word` string — Word transcript (with punctuation if applicable).
            - `start` number — Start time of the word in the call in second. This is relative audio time, not wall time.
            - `end` number — End time of the word in the call in second. This is relative audio time, not wall time.
        - ToolCallInvocationUtterance
          - `role` 'tool_call_invocation', required — This is a tool call invocation.
          - `tool_call_id` string, required — Tool call id, globally unique.
          - `name` string, required — Name of the function in this tool call.
          - `arguments` string, required — Arguments for this tool call, it's a stringified JSON object.
          - `thought_signature` string — Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
        - ToolCallResultUtterance
          - `role` 'tool_call_result', required — This is the result of a tool call.
          - `tool_call_id` string, required — Tool call id, globally unique.
          - `content` string, required — Result of the tool call, can be a string, a stringified json, etc.
          - `successful` boolean — Whether the tool call was successful.
        - NodeTransitionUtterance
          - `role` 'node_transition', required — This is result of a node transition
          - `former_node_id` string, required — Former node id
          - `former_node_name` string, required — Former node name
          - `new_node_id` string, required — New node id
          - `new_node_name` string, required — New node name
          - `transition_type` 'global' | 'global_go_back' | 'interrupt_go_back' | 'normal' — 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.
        - DTMFUtterance
          - `role` 'dtmf', required — Digit pressed by the user from their phone keypad.
          - `digit` string, required — The digit pressed by the user. Will be a single digit string like "1", "2", "3", "*", "#" etc.
        - SmsUtterance
          - `role` 'sms', required — SMS message received from the user during the call (for example while the agent is leaving a voicemail). Not part of the spoken conversation.
          - `content` string, required — Text content of the SMS message.
          - `multimedia` SmsMultimediaItem[] — Multimedia attachments (MMS). Display only; not relayed into the spoken conversation.
            - `url` string, required — URL of the multimedia attachment.
            - `summary` string — Optional textual summary of the attachment.
          - `time_sec` number, required — Time the SMS was received, in seconds relative to the start of the call.
        - InjectedUtterance
          - `role` 'injected', required — External context injected into the conversation via the update-live-call API. Not spoken by either party.
          - `content` string, required — The injected context text.
          - `time_sec` number, required — Time the context was injected, in seconds relative to the start of the call.
    - `recording_url` string — Recording of the call. Available after call ends.
    - `recording_multi_channel_url` string — Recording of the call, with each party's audio stored in a separate channel. Available after the call ends.
    - `scrubbed_recording_url` string — Recording of the call without PII. Available after call ends.
    - `scrubbed_recording_multi_channel_url` string — Recording of the call without PII, with each party's audio stored in a separate channel. Available after the call ends.
    - `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.
    - `knowledge_base_retrieved_contents_url` string — 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` 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.
      - `e2e` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `asr` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `llm` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `llm_websocket_network_rtt` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `tts` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `knowledge_base` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `s2s` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
    - `disconnection_reason` 'user_hangup' | 'agent_hangup' | 'call_transfer' | 'voicemail_reached' | 'ivr_reached' | 'inactivity' | 'max_duration_reached' | 'concurrency_limit_reached' | 'no_concurrency_fallback' | 'no_valid_payment' | 'scam_detected' | 'dial_busy' | 'dial_failed' | 'dial_no_answer' | 'invalid_destination' | 'telephony_provider_permission_denied' | 'telephony_provider_unavailable' | 'sip_routing_error' | 'marked_as_spam' | 'user_declined' | 'error_llm_websocket_open' | 'error_llm_websocket_lost_connection' | 'error_llm_websocket_runtime' | 'error_llm_websocket_corrupt_payload' | 'error_no_audio_received' | 'error_asr' | 'error_retell' | 'error_unknown' | 'error_user_not_joined' | 'registered_call_timeout' | 'transfer_bridged' | 'transfer_cancelled' | 'manual_stopped'
    - `transfer_destination` string, nullable — 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".
    - `call_analysis` CallAnalysis
      - `call_summary` string — A high level summary of the call.
      - `in_voicemail` boolean — Whether the call is entered voicemail.
      - `user_sentiment` 'Negative' | 'Positive' | 'Neutral' | 'Unknown' — Sentiment of the user in the call.
      - `call_successful` boolean — 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` object — Custom analysis data that was extracted based on the schema defined in agent post call analysis data. Can be empty if nothing is specified.
    - `call_cost` object — Cost of the call, including all the products and their costs and discount.
      - `product_costs` ProductCost[], required — List of products with their unit prices and costs in cents
        - `product` string, required — Product name that has a cost associated with it.
        - `unit_price` number — Unit price of the product in cents per second.
        - `cost` number, required — Cost for the product in cents for the duration of the call.
        - `is_transfer_leg_cost` boolean — True if this cost item is for a transfer segment.
      - `total_duration_seconds` number, required — Total duration of the call in seconds
      - `total_duration_unit_price` number, required — Total unit duration price of all products in cents per second
      - `combined_cost` number, required — Combined cost of all individual costs in cents
    - `llm_token_usage` object — LLM token usage of the call, available after call ends. Not populated if using custom LLM, realtime API, or no LLM call is made.
      - `values` number[], required — All the token count values in the call.
      - `average` number, required — Average token count of the call.
      - `num_requests` number, required — Number of requests made to the LLM.
  - V2PhoneCallResponse
    - `call_type` 'phone_call', required — Type of the call. Used to distinguish between web call and phone call.
    - `from_number` string, required — The caller number.
    - `to_number` string, required — The callee number.
    - `direction` 'inbound' | 'outbound', required — Direction of the phone call.
    - `telephony_identifier` object — Telephony identifier of the call, populated when available. Tracking purposes only.
      - `twilio_call_sid` string — Twilio call sid.
    - `call_id` string, required — Unique id of the call. Used to identify the call in the LLM websocket and used to authenticate in the audio websocket.
    - `agent_id` string, required — Corresponding agent id of this call.
    - `agent_name` string — Name of the agent.
    - `agent_version` integer, required — The version of the agent.
    - `call_status` 'registered' | 'not_connected' | 'ongoing' | 'ended' | 'error', 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 hung up, or call transferred. - `error`: Call encountered error.
    - `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 Response Engine prompt and tool description. Only applicable for Response Engine.
    - `collected_dynamic_variables` object — Dynamic variables collected from the call. Only available after the call ends.
    - `custom_sip_headers` object — Custom SIP headers to be added to the call.
    - `data_storage_setting` 'everything' | 'everything_except_pii' | 'basic_attributes_only', nullable — 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.
    - `opt_in_signed_url` boolean — 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` integer — Begin timestamp (milliseconds since epoch) of the call. Available after call starts.
    - `end_timestamp` integer — End timestamp (milliseconds since epoch) of the call. Available after call ends.
    - `transfer_end_timestamp` integer — Transfer end timestamp (milliseconds since epoch) of the call. Available after transfer call ends.
    - `duration_ms` integer — Duration of the call in milliseconds. Available after call ends.
    - `transcript` string — Transcription of the call. Available after call ends.
    - `transcript_object` Utterance[] — Transcript of the call in the format of a list of utterance, with timestamp. Available after call ends.
      - `role` 'agent' | 'user' | 'transfer_target', required — Documents whether this utterance is spoken by agent or user.
      - `content` string, required — Transcript of the utterances.
      - `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.
        - `word` string — Word transcript (with punctuation if applicable).
        - `start` number — Start time of the word in the call in second. This is relative audio time, not wall time.
        - `end` number — End time of the word in the call in second. This is relative audio time, not wall time.
    - `transcript_with_tool_calls` UtteranceOrToolCall[] — 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.
      - union
        - Utterance
          - `role` 'agent' | 'user' | 'transfer_target', required — Documents whether this utterance is spoken by agent or user.
          - `content` string, required — Transcript of the utterances.
          - `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.
            - `word` string — Word transcript (with punctuation if applicable).
            - `start` number — Start time of the word in the call in second. This is relative audio time, not wall time.
            - `end` number — End time of the word in the call in second. This is relative audio time, not wall time.
        - ToolCallInvocationUtterance
          - `role` 'tool_call_invocation', required — This is a tool call invocation.
          - `tool_call_id` string, required — Tool call id, globally unique.
          - `name` string, required — Name of the function in this tool call.
          - `arguments` string, required — Arguments for this tool call, it's a stringified JSON object.
          - `thought_signature` string — Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
        - ToolCallResultUtterance
          - `role` 'tool_call_result', required — This is the result of a tool call.
          - `tool_call_id` string, required — Tool call id, globally unique.
          - `content` string, required — Result of the tool call, can be a string, a stringified json, etc.
          - `successful` boolean — Whether the tool call was successful.
        - NodeTransitionUtterance
          - `role` 'node_transition', required — This is result of a node transition
          - `former_node_id` string, required — Former node id
          - `former_node_name` string, required — Former node name
          - `new_node_id` string, required — New node id
          - `new_node_name` string, required — New node name
          - `transition_type` 'global' | 'global_go_back' | 'interrupt_go_back' | 'normal' — 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.
        - DTMFUtterance
          - `role` 'dtmf', required — Digit pressed by the user from their phone keypad.
          - `digit` string, required — The digit pressed by the user. Will be a single digit string like "1", "2", "3", "*", "#" etc.
        - SmsUtterance
          - `role` 'sms', required — SMS message received from the user during the call (for example while the agent is leaving a voicemail). Not part of the spoken conversation.
          - `content` string, required — Text content of the SMS message.
          - `multimedia` SmsMultimediaItem[] — Multimedia attachments (MMS). Display only; not relayed into the spoken conversation.
            - `url` string, required — URL of the multimedia attachment.
            - `summary` string — Optional textual summary of the attachment.
          - `time_sec` number, required — Time the SMS was received, in seconds relative to the start of the call.
        - InjectedUtterance
          - `role` 'injected', required — External context injected into the conversation via the update-live-call API. Not spoken by either party.
          - `content` string, required — The injected context text.
          - `time_sec` number, required — Time the context was injected, in seconds relative to the start of the call.
    - `scrubbed_transcript_with_tool_calls` UtteranceOrToolCall[] — 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.
      - union
        - Utterance
          - `role` 'agent' | 'user' | 'transfer_target', required — Documents whether this utterance is spoken by agent or user.
          - `content` string, required — Transcript of the utterances.
          - `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.
            - `word` string — Word transcript (with punctuation if applicable).
            - `start` number — Start time of the word in the call in second. This is relative audio time, not wall time.
            - `end` number — End time of the word in the call in second. This is relative audio time, not wall time.
        - ToolCallInvocationUtterance
          - `role` 'tool_call_invocation', required — This is a tool call invocation.
          - `tool_call_id` string, required — Tool call id, globally unique.
          - `name` string, required — Name of the function in this tool call.
          - `arguments` string, required — Arguments for this tool call, it's a stringified JSON object.
          - `thought_signature` string — Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
        - ToolCallResultUtterance
          - `role` 'tool_call_result', required — This is the result of a tool call.
          - `tool_call_id` string, required — Tool call id, globally unique.
          - `content` string, required — Result of the tool call, can be a string, a stringified json, etc.
          - `successful` boolean — Whether the tool call was successful.
        - NodeTransitionUtterance
          - `role` 'node_transition', required — This is result of a node transition
          - `former_node_id` string, required — Former node id
          - `former_node_name` string, required — Former node name
          - `new_node_id` string, required — New node id
          - `new_node_name` string, required — New node name
          - `transition_type` 'global' | 'global_go_back' | 'interrupt_go_back' | 'normal' — 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.
        - DTMFUtterance
          - `role` 'dtmf', required — Digit pressed by the user from their phone keypad.
          - `digit` string, required — The digit pressed by the user. Will be a single digit string like "1", "2", "3", "*", "#" etc.
        - SmsUtterance
          - `role` 'sms', required — SMS message received from the user during the call (for example while the agent is leaving a voicemail). Not part of the spoken conversation.
          - `content` string, required — Text content of the SMS message.
          - `multimedia` SmsMultimediaItem[] — Multimedia attachments (MMS). Display only; not relayed into the spoken conversation.
            - `url` string, required — URL of the multimedia attachment.
            - `summary` string — Optional textual summary of the attachment.
          - `time_sec` number, required — Time the SMS was received, in seconds relative to the start of the call.
        - InjectedUtterance
          - `role` 'injected', required — External context injected into the conversation via the update-live-call API. Not spoken by either party.
          - `content` string, required — The injected context text.
          - `time_sec` number, required — Time the context was injected, in seconds relative to the start of the call.
    - `recording_url` string — Recording of the call. Available after call ends.
    - `recording_multi_channel_url` string — Recording of the call, with each party's audio stored in a separate channel. Available after the call ends.
    - `scrubbed_recording_url` string — Recording of the call without PII. Available after call ends.
    - `scrubbed_recording_multi_channel_url` string — Recording of the call without PII, with each party's audio stored in a separate channel. Available after the call ends.
    - `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.
    - `knowledge_base_retrieved_contents_url` string — 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` 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.
      - `e2e` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `asr` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `llm` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `llm_websocket_network_rtt` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `tts` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `knowledge_base` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
      - `s2s` CallLatency
        - `p50` number — 50 percentile of latency, measured in milliseconds.
        - `p90` number — 90 percentile of latency, measured in milliseconds.
        - `p95` number — 95 percentile of latency, measured in milliseconds.
        - `p99` number — 99 percentile of latency, measured in milliseconds.
        - `max` number — Maximum latency in the call, measured in milliseconds.
        - `min` number — Minimum latency in the call, measured in milliseconds.
        - `num` number — Number of data points (number of times latency is tracked).
        - `values` number[] — All the latency data points in the call, measured in milliseconds.
    - `disconnection_reason` 'user_hangup' | 'agent_hangup' | 'call_transfer' | 'voicemail_reached' | 'ivr_reached' | 'inactivity' | 'max_duration_reached' | 'concurrency_limit_reached' | 'no_concurrency_fallback' | 'no_valid_payment' | 'scam_detected' | 'dial_busy' | 'dial_failed' | 'dial_no_answer' | 'invalid_destination' | 'telephony_provider_permission_denied' | 'telephony_provider_unavailable' | 'sip_routing_error' | 'marked_as_spam' | 'user_declined' | 'error_llm_websocket_open' | 'error_llm_websocket_lost_connection' | 'error_llm_websocket_runtime' | 'error_llm_websocket_corrupt_payload' | 'error_no_audio_received' | 'error_asr' | 'error_retell' | 'error_unknown' | 'error_user_not_joined' | 'registered_call_timeout' | 'transfer_bridged' | 'transfer_cancelled' | 'manual_stopped'
    - `transfer_destination` string, nullable — 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".
    - `call_analysis` CallAnalysis
      - `call_summary` string — A high level summary of the call.
      - `in_voicemail` boolean — Whether the call is entered voicemail.
      - `user_sentiment` 'Negative' | 'Positive' | 'Neutral' | 'Unknown' — Sentiment of the user in the call.
      - `call_successful` boolean — 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` object — Custom analysis data that was extracted based on the schema defined in agent post call analysis data. Can be empty if nothing is specified.
    - `call_cost` object — Cost of the call, including all the products and their costs and discount.
      - `product_costs` ProductCost[], required — List of products with their unit prices and costs in cents
        - `product` string, required — Product name that has a cost associated with it.
        - `unit_price` number — Unit price of the product in cents per second.
        - `cost` number, required — Cost for the product in cents for the duration of the call.
        - `is_transfer_leg_cost` boolean — True if this cost item is for a transfer segment.
      - `total_duration_seconds` number, required — Total duration of the call in seconds
      - `total_duration_unit_price` number, required — Total unit duration price of all products in cents per second
      - `combined_cost` number, required — Combined cost of all individual costs in cents
    - `llm_token_usage` object — LLM token usage of the call, available after call ends. Not populated if using custom LLM, realtime API, or no LLM call is made.
      - `values` number[], required — All the token count values in the call.
      - `average` number, required — Average token count of the call.
      - `num_requests` number, required — Number of requests made to the LLM.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `422` — Unprocessable Content
- `500` — Internal Server Error

---

[API](https://skmtc.net/retellai/apis/retell-sdk.md) · [All operations](https://skmtc.net/retellai/apis/retell-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/retellai/retell-sdk/versions/2a182bedbfc5/schema)