Skip to main content
POST
/
agent-playground-completion
/
{agent_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 response = await client.playground.completion('agent_id', {
  messages: [
    { content: "Hi, I'd like to check my appointment.", role: 'user' },
    { content: 'Sure! Could you please provide your name?', role: 'agent' },
    { content: 'My name is John Smith.', role: 'user' },
  ],
});

console.log(response.current_node_id);
{
  "messages": [
    {
      "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "role": "agent",
      "content": "hi how are you doing?",
      "created_timestamp": 1703302428855
    }
  ],
  "current_state": "greeting",
  "current_node_id": "node_abc123",
  "dynamic_variables": {
    "customer_name": "John Doe"
  },
  "call_ended": false,
  "knowledge_base_retrieved_contents": [
    "Our business hours are Monday through Friday, 9am to 5pm."
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.retellai.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
agent_id
string
required

Unique id of the agent.

Query Parameters

​
version

Agent version to use. Defaults to latest. Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version (or latest) is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.

Required range: x >= 0
Example:

1

Body

application/json
​
messages
object[]
required

Full conversation history, same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted.

Same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted.

Example:
[
  {
    "role": "user",
    "content": "Hi, I'd like to check my appointment."
  },
  {
    "role": "agent",
    "content": "Sure! Could you please provide your name?"
  },
  {
    "role": "user",
    "content": "My name is John Smith."
  }
]
​
dynamic_variables
object

Key-value pairs for dynamic variable substitution.

Example:
{
  "customer_name": "John Smith",
  "customer_phone": "444-223-3564"
}
​
tool_mocks
object[]

Optional mock responses for tools. When provided, the agent uses these instead of executing real tool calls.

​
current_state
string

Current state name for retell-llm agents. Used to resume from a specific state.

Example:

"greeting"

​
current_node_id
string

Current node id for conversation-flow agents. Used to resume from a specific node. Must be provided together with component_id when testing components.

Example:

"start-node-abc123"

​
component_id
string

Conversation flow component id. Required when current_node_id refers to a node within a component.

Example:

"component_xyz789"

Response

Successfully generated playground completion.

​
messages
object[]
required

New messages generated by the agent. Same shape as chat completion response messages. Does not include the input messages.

​
current_state
string

Current state name (retell-llm agents).

Example:

"greeting"

​
current_node_id
string

Current node id (conversation-flow agents).

Example:

"node_abc123"

​
dynamic_variables
object

Updated dynamic variables after this turn.

Example:
{ "customer_name": "John Doe" }
​
call_ended
boolean

Whether the agent ended the conversation.

Example:

false

​
knowledge_base_retrieved_contents
string[]

Knowledge base chunks retrieved for this turn.

Example:
[
  "Our business hours are Monday through Friday, 9am to 5pm."
]