Skip to main content
POST
Test an agent with a script

Authorizations

Authorization
string
header
required

Your workspace secret key, sk_live_ followed by 32 hex characters. Create one in the console under Developers.

Path Parameters

agent_id
string
required

The agent's id (agt_…).

Body

application/json
lines
string[]
required
allowed_tools
string[]
analysis
boolean
call_settings
object

The voice and languages for this call only, over the agent's. Every key is optional; a key left out keeps the agent's value (or, on a campaign contact, the request's). The same object is accepted on POST /v2/calls, on a campaign contact and in a pre_call tool's result. An unknown key or a value that fails these rules is 400 invalid_request naming it.

metadata
object
variables
object

Response

The conversation and its analysis

A scripted test's answer (POST /v2/agents/{id}/test_script): the conversation line by line, then the test call as GET /v2/calls/{id} shows it once settled.

agent_id
string
required

The agent tested.

call
null | object
required

The test call once settled: status, cost (billed by LLM tokens), analysis and outcome. analysis is still pending when it did not finish in time; read GET /v2/calls/{id} later.

call_id
string
required

The test call (channel text, test true): readable with GET /v2/calls/{id}, its transcript and analysis.

greeting
string[]
required

The agent's opening line(s), before the first customer line; empty when it waits for the customer.

object
any
required

Always test_script.

status
enum<string>
required

completed: every line was sent; ended_early: the agent ended the conversation before the last line (see ended_reason); timed_out: the time budget ran out and the rest were not sent; failed: the conversation could not be continued.

Available options:
completed,
ended_early,
timed_out,
failed
turns
object[]
required

One per customer line, in order.

ended_reason
string

How the conversation ended on the agent's side: customer-ended-call when the script hung up, assistant-ended-call when the agent did.