Skip to main content
POST
Create Simulation
Integration Prompt for AI Agents
New: agent_version_idDeprecated: prompt_id. Same uuid, still works. If both are sent and they differ, the request is 400.
Given the agent ID, and simulation settings, this endpoint creates a simulation and returns the simulation ID.

Headers

X-Organization-Id
string
X-API-Key
string
required

API key required to authenticate requests.

Body

application/json

Pydantic model for simulation request

agent_id
string
required

ID of the agent to be used in the simulation

name
string | null

Name of the simulation

description
string | null

Description of the simulation

prompt_id
string<uuid> | null
deprecated

Deprecated. Use agent_version_id. Same uuid, still works.

agent_version_id
string<uuid> | null

Optional default agent version UUID for this simulation

knowledge_base_id
string<uuid> | null

Optional default knowledge base UUID for this simulation

max_concurrent
integer | null

Maximum number of concurrent calls in the simulation (max 500)

Required range: 0 < x <= 500
hangup_on_transfer
boolean | null
default:false

Whether to hang up the call on transfer

max_call_duration
integer | null
default:10

Maximum duration of each call (default is 10). Units specified by max_call_duration_units

max_call_duration_units
enum<string> | null
default:minutes

Units for max_call_duration: 'minutes' (default) or 'seconds'

Available options:
minutes,
seconds
ringing_timeout
integer | null
default:300

Ringing timeout in seconds for SIP trunks (default 300s)

digital_humans_settings
DigitalHumansSettings · object | null

Settings for digital humans in the simulation

selected_custom_metrics
string<uuid>[] | null

Custom metric IDs to enable for this simulation

custom_metrics_failing_threshold
integer | null

Score threshold below which a custom metric is considered failing (0-100)

Required range: 0 <= x <= 100
custom_metrics_passing_threshold
integer | null

Score threshold at or above which a custom metric is considered passing (0-100)

Required range: 0 <= x <= 100
runs_per_digital_human
integer | null

Number of simulation runs to execute per digital human (defaults to 1 when omitted)

Required range: x > 0
delay_between_tests_seconds
number | null

seconds to wait after a test completes before the next launches (0 = off)

Required range: 0 <= x <= 300
inactivity_timeout_seconds
integer | null

seconds to wait for an agent reply before ending a text conversation (300-1800 = 5-30 min); defaults to 300 when unset

Required range: 300 <= x <= 1800
always_on
boolean | null
default:false

When true, simulation has always-on digital humans configured

Response

Successful Response

simulation_id
integer
required

ID of the created simulation

status
string
default:200

Status of the response