POST
/v1/convai/agents/{agent_id}/simulate-conversation
ElevenLabs APISimulates A Conversation
- Base URL
- https://api.elevenlabs.io
- Auth
- xi-api-key: <ELEVENLABS_API_KEY>
- Last verified
- 2026-09-03 · upstream hash matched
Actions
Agents: curl -H "Accept: text/markdown" this URL
→ 216 tokens · Vary: Accept
→ 216 tokens · Vary: Accept
Critical gotchas
Authentication uses the non-standard xi-api-key header, not Authorization: Bearer. Sending a Bearer token returns HTTP 401.
Text-to-speech responses are raw binary audio, not JSON. Write the body to a file (--output speech.mp3) rather than parsing it.
cURL
curl -X POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/simulate-conversation' \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "simulation_specification": { "simulated_user_config": { "disable_first_message_interruptions": false, "first_message": "Hello, how can I help you today?", "language": "en" }, "tool_mock_config": {}, "partial_conversation_history": [ { "role": "user", "agent_metadata": { "agent_id": "string", "branch_id": "string", "workflow_node_id": "string", "version_id": "string" }, "message": "string", "multivoice_message": { "parts": [ "[recursive or deeply nested schema]" ] }, "tool_calls": [ { "type": "[recursive or deeply nested schema]", "request_id": "[recursive or deeply nested schema]", "tool_name": "[recursive or deeply nested schema]", "params_as_json": "[recursive or deeply nested schema]", "tool_has_been_called": "[recursive or deeply nested schema]", "tool_details": "[recursive or deeply nested schema]" } ], "tool_results": [ { "request_id": "[recursive or deeply nested schema]", "tool_name": "[recursive or deeply nested schema]", "result_value": "[recursive or deeply nested schema]", "is_error": "[recursive or deeply nested schema]", "is_blocked": "[recursive or deeply nested schema]", "tool_has_been_called": "[recursive or deeply nested schema]", "tool_latency_secs": "[recursive or deeply nested schema]", "error_type": "[recursive or deeply nested schema]", "raw_error_message": "[recursive or deeply nested schema]", "dynamic_variable_updates": "[recursive or deeply nested schema]", "type": "[recursive or deeply nested schema]" } ], "feedback": { "score": "like", "time_in_call_secs": 0 }, "llm_override": "string", "producing_llm": "string", "time_in_call_secs": 0, "conversation_turn_metrics": { "metrics": {}, "convai_asr_provider": "string", "convai_tts_model": "string", "convai_tts_cascade": "string" }, "rag_retrieval_info": { "chunks": [ "[recursive or deeply nested schema]" ], "embedding_model": "e5_mistral_7b_instruct", "retrieval_query": "string", "rag_latency_secs": 0, "used_chunk_ids": [ "[recursive or deeply nested schema]" ] }, "llm_usage": { "model_usage": {} }, "interrupted": false, "ignored_as_backchannel": false, "original_message": "string", "reasoning": [ { "summary": "[recursive or deeply nested schema]", "provider_redact": "[recursive or deeply nested schema]" } ], "source_medium": "audio", "source_event_id": 0, "used_static_kb_document_ids": [ "string" ], "user_identifier": "string", "id": "string", "triggered_guardrails": [ { "guardrail_type": "[recursive or deeply nested schema]", "guardrail_name": "[recursive or deeply nested schema]" } ] } ], "dynamic_variables": {} }, "extra_evaluation_criteria": [ { "id": "string", "name": "string", "type": "prompt", "conversation_goal_prompt": "string", "use_knowledge_base": false, "scope": "conversation", "llm": "gpt-4o-mini", "scoring_mode": "binary", "max_score": 100, "score_instructions": "string" } ], "new_turns_limit": 10000}'Get a free ElevenLabs API key → sponsored
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | path | string | Yes | The id of an agent. This is returned on agent creation. |
| simulation_specification | body | object | Yes | A specification that will be used to simulate a conversation between an agent and an AI user. |
| extra_evaluation_criteria | body | object[] | No | A list of evaluation criteria to test |
| new_turns_limit | body | integer | No | Maximum number of new turns to generate in the conversation simulation |
Response 200 OK
{
"simulated_conversation": [
{
"role": "user",
"agent_metadata": {
"agent_id": "string",
"branch_id": "string",
"workflow_node_id": "string",
"version_id": "string"
},
"message": "string",
"multivoice_message": {
"parts": [
{
"text": "[recursive or deeply nested schema]",
"voice_label": "[recursive or deeply nested schema]",
"time_in_call_secs": "[recursive or deeply nested schema]"
}
]
},
"tool_calls": [
{
"type": "system",
"request_id": "string",
"tool_name": "string",
"params_as_json": "string",
"tool_has_been_called": true,
"tool_details": {
"type": "[recursive or deeply nested schema]",
"method": "[recursive or deeply nested schema]",
"url": "[recursive or deeply nested schema]",
"headers": "[recursive or deeply nested schema]",
"path_params": "[recursive or deeply nested schema]",
"query_params": "[recursive or deeply nested schema]",
"body": "[recursive or deeply nested schema]"
}
}
],
"tool_results": [
{
"request_id": "string",
"tool_name": "string",
"result_value": "string",
"is_error": true,
"is_blocked": false,
"tool_has_been_called": true,
"tool_latency_secs": 0,
"error_type": "",
"raw_error_message": "",
"dynamic_variable_updates": [
"[recursive or deeply nested schema]"
],
"type": "client"
}
],
"feedback": {
"score": "like",
"time_in_call_secs": 0
},
"llm_override": "string",
"producing_llm": "string",
"time_in_call_secs": 0,
"conversation_turn_metrics": {
"metrics": {},
"convai_asr_provider": "string",
"convai_tts_model": "string",
"convai_tts_cascade": "string"
},
"rag_retrieval_info": {
"chunks": [
{
"document_id": "[recursive or deeply nested schema]",
"chunk_id": "[recursive or deeply nested schema]",
"vector_distance": "[recursive or deeply nested schema]"
}
],
"embedding_model": "e5_mistral_7b_instruct",
"retrieval_query": "string",
"rag_latency_secs": 0,
"used_chunk_ids": [
"string"
]
},
"llm_usage": {
"model_usage": {}
},
"interrupted": false,
"ignored_as_backchannel": false,
"original_message": "string",
"reasoning": [
{
"summary": "string",
"provider_redact": false
}
],
"source_medium": "audio",
"source_event_id": 0,
"used_static_kb_document_ids": [
"string"
],
"user_identifier": "string",
"id": "string",
"triggered_guardrails": [
{
"guardrail_type": "custom",
"guardrail_name": "string"
}
],
"file_input": {
"file_id": "string",
"original_filename": "string",
"mime_type": "string",
"file_url": "string"
},
"file_inputs": [
{
"file_id": "string",
"original_filename": "string",
"mime_type": "string",
"file_url": "string"
}
],
"contextual_update_info": {
"context_id": "string",
"is_superseded": false
},
"reasoned": false
}
],
"analysis": {
"evaluation_criteria_results": {},
"data_collection_results": {},
"evaluation_criteria_results_list": [
{
"criteria_id": "string",
"result": "success",
"rationale": "string",
"scoring_mode": "binary",
"score": 0,
"max_score": 0
}
],
"data_collection_results_list": [
{
"data_collection_id": "string",
"name": "string",
"value": {},
"json_schema": {
"description": "A user-provided message",
"type": "string"
},
"rationale": "string"
}
],
"call_successful": "success",
"call_success_score": 0,
"transcript_summary": "string",
"call_summary_title": "string",
"scoped": [
{
"scope": "conversation",
"source_agent_id": "string",
"source_branch_id": "string",
"evaluation_criteria_results": {},
"data_collection_results": {},
"successful": "success",
"success_score": 0
}
]
}
}