For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Connect
BlogHelp CenterAPI PricingSign up
OverviewElevenCreativeElevenAgentsElevenAPIReception AIAPI referenceChangelog
OverviewElevenCreativeElevenAgentsElevenAPIReception AIAPI referenceChangelog
  • API reference
    • Introduction
    • Authentication
    • Streaming
  • ElevenAgents
      • POSTCreate agent
      • GETGet agent
      • GETList agents
      • PATCHUpdate agent
      • DELDelete agent
      • POSTDuplicate agent
      • GETGet link
      • POSTSimulate conversation
      • POSTStream simulate conversation
      • POSTCalculate expected LLM usage
      • GETGet agent summaries
  • ElevenAPI
  • ElevenCreative
  • Core Resources
  • Workspace
  • Legacy
  • Conversational AI
LogoLogo
Login
Login
Connect
BlogHelp CenterAPI PricingSign up
ElevenAgentsAgents

Simulate conversation

POST
/v1/convai/agents/:agent_id/simulate-conversation
POST
/v1/convai/agents/:agent_id/simulate-conversation
$curl -X POST https://api.elevenlabs.io/v1/convai/agents/agent_id/simulate-conversation \
> -H "Content-Type: application/json" \
> -d '{
> "simulation_specification": {
> "simulated_user_config": {
> "first_message": "Hello, how can I help you today?",
> "language": "en",
> "disable_first_message_interruptions": false
> }
> }
>}'
1{
2 "simulated_conversation": [
3 {
4 "role": "user",
5 "time_in_call_secs": 1,
6 "agent_metadata": {
7 "agent_id": "string",
8 "branch_id": "string",
9 "workflow_node_id": "string",
10 "version_id": "string"
11 },
12 "message": "string",
13 "multivoice_message": {
14 "parts": [
15 {
16 "text": "string",
17 "voice_label": "string",
18 "time_in_call_secs": 1
19 }
20 ]
21 },
22 "tool_calls": [
23 {
24 "request_id": "string",
25 "tool_name": "string",
26 "params_as_json": "string",
27 "tool_has_been_called": true,
28 "type": "system",
29 "tool_details": {
30 "type": "webhook",
31 "method": "string",
32 "url": "string",
33 "body": "string",
34 "headers": {},
35 "path_params": {},
36 "query_params": {}
37 }
38 }
39 ],
40 "tool_results": [
41 {
42 "request_id": "string",
43 "tool_name": "string",
44 "result_value": "string",
45 "is_error": true,
46 "is_blocked": false,
47 "tool_has_been_called": true,
48 "tool_latency_secs": 0,
49 "error_type": "",
50 "raw_error_message": "",
51 "dynamic_variable_updates": [
52 {
53 "variable_name": "string",
54 "old_value": "string",
55 "new_value": "string",
56 "updated_at": 1.1,
57 "tool_name": "string",
58 "tool_request_id": "string"
59 }
60 ],
61 "type": "client"
62 }
63 ],
64 "feedback": {
65 "score": "like",
66 "time_in_call_secs": 1
67 },
68 "llm_override": "string",
69 "conversation_turn_metrics": {
70 "metrics": {},
71 "convai_asr_provider": "string",
72 "convai_tts_model": "string",
73 "convai_tts_cascade": "string"
74 },
75 "rag_retrieval_info": {
76 "chunks": [
77 {
78 "document_id": "string",
79 "chunk_id": "string",
80 "vector_distance": 1.1
81 }
82 ],
83 "embedding_model": "e5_mistral_7b_instruct",
84 "retrieval_query": "string",
85 "rag_latency_secs": 1.1,
86 "used_chunk_ids": [
87 "string"
88 ]
89 },
90 "llm_usage": {
91 "model_usage": {}
92 },
93 "interrupted": false,
94 "original_message": "string",
95 "source_medium": "audio",
96 "source_event_id": 1,
97 "used_static_kb_document_ids": [
98 "string"
99 ],
100 "file_input": {
101 "file_id": "string",
102 "original_filename": "string",
103 "mime_type": "string",
104 "file_url": "string"
105 },
106 "contextual_update_info": {
107 "context_id": "string",
108 "is_superseded": false
109 }
110 }
111 ],
112 "analysis": {
113 "call_successful": "success",
114 "transcript_summary": "string",
115 "evaluation_criteria_results": {},
116 "data_collection_results": {},
117 "evaluation_criteria_results_list": [
118 {
119 "criteria_id": "string",
120 "result": "success",
121 "rationale": "string"
122 }
123 ],
124 "data_collection_results_list": [
125 {
126 "data_collection_id": "string",
127 "rationale": "string",
128 "value": null,
129 "json_schema": {
130 "type": "string",
131 "description": "A user-provided message"
132 }
133 }
134 ],
135 "call_summary_title": "string",
136 "scoped": [
137 {
138 "scope": "conversation",
139 "source_agent_id": "string",
140 "successful": "success",
141 "source_branch_id": "string",
142 "evaluation_criteria_results": {},
143 "data_collection_results": {}
144 }
145 ]
146 }
147}
Run a conversation between the agent and a simulated user.
Was this page helpful?
Previous

Stream simulate conversation

Next
Built with

Path parameters

agent_idstringRequired
The id of an agent. This is returned on agent creation.

Headers

xi-api-keystringOptional

Request

This endpoint expects an object.
simulation_specificationobjectRequired
A specification detailing how the conversation should be simulated
extra_evaluation_criterialist of objects or nullOptional
A list of evaluation criteria to test
new_turns_limitintegerOptionalDefaults to 10000
Maximum number of new turns to generate in the conversation simulation

Response

Successful Response
simulated_conversationlist of objects
analysisobject

Errors

422
Unprocessable Entity Error