Update Call

PATCH

update-call

{call_id}

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const callResponse = await client.call.update('call_a4441234567890777c4a4a123e6', {
  data_storage_setting: 'everything_except_pii',
  metadata: { customer_id: 'cust_123', notes: 'Follow-up required' },
});

console.log(callResponse);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
call_response = client.call.update(
    call_id="call_a4441234567890777c4a4a123e6",
    data_storage_setting="everything_except_pii",
    metadata={
        "customer_id": "cust_123",
        "notes": "Follow-up required",
    },
)
print(call_response)

curl --request PATCH \
  --url https://api.retellai.com/v2/update-call/{call_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "customer_id": "cust_123",
    "notes": "Follow-up required"
  },
  "data_storage_setting": "everything_except_pii"
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/v2/update-call/{call_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'customer_id' => 'cust_123',
        'notes' => 'Follow-up required'
    ],
    'data_storage_setting' => 'everything_except_pii'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.retellai.com/v2/update-call/{call_id}"

	payload := strings.NewReader("{\n  \"metadata\": {\n    \"customer_id\": \"cust_123\",\n    \"notes\": \"Follow-up required\"\n  },\n  \"data_storage_setting\": \"everything_except_pii\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.retellai.com/v2/update-call/{call_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"customer_id\": \"cust_123\",\n    \"notes\": \"Follow-up required\"\n  },\n  \"data_storage_setting\": \"everything_except_pii\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/v2/update-call/{call_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {\n    \"customer_id\": \"cust_123\",\n    \"notes\": \"Follow-up required\"\n  },\n  \"data_storage_setting\": \"everything_except_pii\"\n}"

response = http.request(request)
puts response.read_body

{
  "call_type": "web_call",
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p",
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_version": 1,
  "call_status": "registered",
  "agent_name": "My Agent",
  "agent_tag": "prod",
  "metadata": {},
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "collected_dynamic_variables": {
    "last_node_name": "Test node"
  },
  "custom_sip_headers": {
    "X-Custom-Header": "Custom Value"
  },
  "data_storage_setting": "everything",
  "opt_in_signed_url": true,
  "start_timestamp": 1703302407333,
  "end_timestamp": 1703302428855,
  "transfer_end_timestamp": 1703302628855,
  "duration_ms": 10000,
  "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
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "scrubbed_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "pre_session_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "scrubbed_pre_session_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "post_session_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "scrubbed_post_session_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
  "recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
  "scrubbed_recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
  "scrubbed_recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
  "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt",
  "knowledge_base_retrieved_contents_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt",
  "latency": {
    "e2e": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10,
      "values": [
        123
      ]
    },
    "asr": {
      "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",
  "transfer_destination": "+12137771234",
  "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",
        "cost": 60,
        "unit_price": 1,
        "is_transfer_leg_cost": true
      }
    ],
    "total_duration_seconds": 60,
    "total_duration_unit_price": 1,
    "combined_cost": 70
  },
  "llm_token_usage": {
    "values": [
      123
    ],
    "average": 123,
    "num_requests": 123
  }
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Cannot find requested asset under given api key."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Authorizations

Authorization

string

header

required

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

Path Parameters

call_id

string

required

The call id of the call to be updated.

Example:

"call_a4441234567890777c4a4a123e6"

Body

application/json

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.

Example:

{
  "customer_id": "cust_123",
  "notes": "Follow-up required"
}

data_storage_setting

enum<string>

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.

Available options:

everything,

everything_except_pii,

basic_attributes_only

Example:

"everything_except_pii"

custom_attributes

object

Custom attributes for the call, as key-value pairs. Each attribute must first be defined for your organization in the Retell dashboard (Call History → Actions → Custom attributes) before it can be set here. The object key must match the id of an existing organization-level custom attribute; keys that do not match a defined attribute are ignored and will not be saved. Values must be a string, number, or boolean.

Show child attributes

Example:

{
  "custom_attribute_1": "value1",
  "custom_attribute_2": "value2"
}

Response

Call metadata updated successfully

Option 1
Option 2

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 the call in the LLM websocket and used to authenticate in the audio websocket.

Example:

"Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6"

agent_id

string

required

Corresponding agent id of this call.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

agent_version

integer

required

The version of the agent.

Example:

1

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 hung up, or call transferred.
error: Call encountered error.

Available options:

registered,

not_connected,

ongoing,

ended,

error

Example:

"registered"

agent_name

string

Name of the agent.

Example:

"My Agent"

agent_tag

string | null

Tag pointing at the agent version used for this call, captured at call creation time and frozen thereafter (unaffected by later tag reassignments). Populated whether the caller dispatched by tag, numeric version, "latest", or "latest_published" — when the caller specified a tag, that tag wins; otherwise the most-recently- assigned tag on the resolved version is used. Absent when no tag points at the resolved version (or for calls created before this field was introduced).

Example:

"prod"

metadata

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.

Show child attributes

Example:

{ "customer_name": "John Doe" }

collected_dynamic_variables

object

Dynamic variables collected from the call. Only available after the call ends.

Show child attributes

Example:

{ "last_node_name": "Test node" }

custom_sip_headers

object

Custom SIP headers to be added to the call.

Show child attributes

Example:

{ "X-Custom-Header": "Custom Value" }

data_storage_setting

enum<string> | null

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.

Available options:

everything,

everything_except_pii,

basic_attributes_only

Example:

"everything"

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.

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

transfer_end_timestamp

integer

Transfer end timestamp (milliseconds since epoch) of the call. Available after transfer call ends.

Example:

1703302628855

duration_ms

integer

Duration of the call in milliseconds. Available after call ends.

Example:

10000

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.

Show child attributes

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.

Show child attributes

scrubbed_transcript_with_tool_calls

object[]

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.

Show child attributes

pre_session_transcript_with_tool_calls

object[]

Tool call invocations and results of integration tools run before the session started (pre-session). Stored separately from the main transcript. Available after call ends if pre-session integration tools ran.

Show child attributes

scrubbed_pre_session_transcript_with_tool_calls

object[]

Pre-session integration tool call invocations and results, without PII. Available after call ends if pre-session integration tools ran and PII scrubbing is enabled.

Show child attributes

post_session_transcript_with_tool_calls

object[]

Tool call invocations and results of integration tools run after post-call analysis (post-session). Stored separately from the main transcript. Available after call ends if post-session integration tools ran.

Show child attributes

scrubbed_post_session_transcript_with_tool_calls

object[]

Post-session integration tool call invocations and results, without PII. Available after call ends if post-session integration tools ran and PII scrubbing is enabled.

Show child attributes

recording_url

string

Recording of the call. Available after call ends.

Example:

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

recording_multi_channel_url

string

Recording of the call, with each party's audio stored in a separate channel. Available after the call ends.

Example:

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

scrubbed_recording_url

string

Recording of the call without PII. Available after call ends.

Example:

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

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.

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.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"

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.

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.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.

Show child attributes

disconnection_reason

enum<string>

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

Available options:

user_hangup,

agent_hangup,

user_requested_dnc,

user_requested_callback,

call_transfer,

voicemail_reached,

ivr_reached,

inactivity,

max_duration_reached,

concurrency_limit_reached,

no_concurrency_fallback,

no_valid_payment,

credit_exhausted,

budget_reached,

scam_detected,

dial_busy,

dial_failed,

dial_no_answer,

invalid_destination,

telephony_provider_permission_denied,

telephony_provider_unavailable,

sip_routing_error,

marked_as_spam,

network_blocked,

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,

call_take_over

Example:

"agent_hangup"

transfer_destination

string | null

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".

Example:

"+12137771234"

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.

Show child attributes

call_cost

object

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

Show child attributes

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.

Show child attributes

⌘I

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const callResponse = await client.call.update('call_a4441234567890777c4a4a123e6', {
  data_storage_setting: 'everything_except_pii',
  metadata: { customer_id: 'cust_123', notes: 'Follow-up required' },
});

console.log(callResponse);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
call_response = client.call.update(
    call_id="call_a4441234567890777c4a4a123e6",
    data_storage_setting="everything_except_pii",
    metadata={
        "customer_id": "cust_123",
        "notes": "Follow-up required",
    },
)
print(call_response)

curl --request PATCH \
  --url https://api.retellai.com/v2/update-call/{call_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "customer_id": "cust_123",
    "notes": "Follow-up required"
  },
  "data_storage_setting": "everything_except_pii"
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/v2/update-call/{call_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'customer_id' => 'cust_123',
        'notes' => 'Follow-up required'
    ],
    'data_storage_setting' => 'everything_except_pii'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.retellai.com/v2/update-call/{call_id}"

	payload := strings.NewReader("{\n  \"metadata\": {\n    \"customer_id\": \"cust_123\",\n    \"notes\": \"Follow-up required\"\n  },\n  \"data_storage_setting\": \"everything_except_pii\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.retellai.com/v2/update-call/{call_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"customer_id\": \"cust_123\",\n    \"notes\": \"Follow-up required\"\n  },\n  \"data_storage_setting\": \"everything_except_pii\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/v2/update-call/{call_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {\n    \"customer_id\": \"cust_123\",\n    \"notes\": \"Follow-up required\"\n  },\n  \"data_storage_setting\": \"everything_except_pii\"\n}"

response = http.request(request)
puts response.read_body

{
  "call_type": "web_call",
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p",
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_version": 1,
  "call_status": "registered",
  "agent_name": "My Agent",
  "agent_tag": "prod",
  "metadata": {},
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "collected_dynamic_variables": {
    "last_node_name": "Test node"
  },
  "custom_sip_headers": {
    "X-Custom-Header": "Custom Value"
  },
  "data_storage_setting": "everything",
  "opt_in_signed_url": true,
  "start_timestamp": 1703302407333,
  "end_timestamp": 1703302428855,
  "transfer_end_timestamp": 1703302628855,
  "duration_ms": 10000,
  "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
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "scrubbed_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "pre_session_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "scrubbed_pre_session_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "post_session_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "scrubbed_post_session_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ],
      "metadata": {
        "response_id": 123,
        "interrupt_id": 123,
        "is_backchannel": true,
        "interrupted": true,
        "backup_model_used": {
          "model": "<string>",
          "primary_model": "<string>",
          "backup_model": "<string>",
          "reason": "primary_failed",
          "selection_latency_ms": 123,
          "primary_ready_ms": 123,
          "backup_ready_ms": 123
        }
      }
    }
  ],
  "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
  "recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
  "scrubbed_recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
  "scrubbed_recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
  "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt",
  "knowledge_base_retrieved_contents_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt",
  "latency": {
    "e2e": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10,
      "values": [
        123
      ]
    },
    "asr": {
      "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",
  "transfer_destination": "+12137771234",
  "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",
        "cost": 60,
        "unit_price": 1,
        "is_transfer_leg_cost": true
      }
    ],
    "total_duration_seconds": 60,
    "total_duration_unit_price": 1,
    "combined_cost": 70
  },
  "llm_token_usage": {
    "values": [
      123
    ],
    "average": 123,
    "num_requests": 123
  }
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Cannot find requested asset under given api key."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Call

Chat

Playground

Phone Number

Voice Agent

Chat Agent

Retell LLM Response Engine (for single / multi prompt agent)

Conversation Flow Response Engine (for conversation flow agent)

Conversation Flow Subflows

MCP Tool

Knowledge Base

Voice

Batch call

Contact

App

CRM

Test Case Definitions

Batch Tests

Test Runs

Account

Custom Telephony

Custom LLM

Authorizations

Path Parameters

Body

Response