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