POST
POST /v1/convai/agents/{agent_id}/simulate-conversation/stream — ElevenLabs API
ElevenLabs APISimulates A Conversation (Stream)
- Base URL
- https://api.elevenlabs.io
- Auth
- xi-api-key: <ELEVENLABS_API_KEY>
- Last verified
- 2026-10-20 · upstream hash matched
Actions Try in browser→
Agents: curl -H "Accept: text/markdown" this URL
→ 229 tokens · Vary: Accept
→ 229 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": "example-agent-id", "branch_id": "example-branch-id", "workflow_node_id": "example-workflow-node-id", "version_id": "example-version-id" }, "message": "example-message", "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]", "tool_id": "[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": "example-llm-override", "producing_llm": "example-producing-llm", "time_in_call_secs": 0, "conversation_turn_metrics": { "metrics": {}, "convai_asr_provider": "example-convai-asr-provider", "convai_tts_model": "example-convai-tts-model", "convai_tts_cascade": "example-convai-tts-cascade", "voice_id": "example-voice-id" }, "rag_retrieval_info": { "chunks": [ "[recursive or deeply nested schema]" ], "embedding_model": "e5_mistral_7b_instruct", "retrieval_query": "example-retrieval-query", "rag_latency_secs": 0, "used_chunk_ids": [ "[recursive or deeply nested schema]" ] }, "llm_usage": { "model_usage": {} }, "interrupted": false, "ignored_as_backchannel": false, "platform_event": "user_turn_timeout", "original_message": "example-original-message", "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": [ "example-used-static-kb-document-ids" ], "user_identifier": "example-user-identifier", "id": "example-id", "triggered_guardrails": [ { "guardrail_type": "[recursive or deeply nested schema]", "guardrail_name": "[recursive or deeply nested schema]" } ] } ], "dynamic_variables": {} }, "extra_evaluation_criteria": [ { "id": "example-id", "name": "example-name", "type": "prompt", "conversation_goal_prompt": "example-conversation-goal-prompt", "use_knowledge_base": false, "scope": "conversation", "llm": "gpt-4o-mini", "scoring_mode": "example-scoring-mode", "max_score": 100, "score_instructions": "example-score-instructions" } ], "new_turns_limit": 100}'
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
nullGet a free ElevenLabs API key → sponsored
Affiliate link - we may earn a commission, at no extra cost to you.