POST
/v1/convai/agents/{agent_id}/simulate-conversation/stream
ElevenLabs APISimulates A Conversation (Stream)
- 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
→ 218 tokens · Vary: Accept
→ 218 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/stream' \ -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
null