apicheats.dev elevenlabs/llms.txt Raw .md
POST

/v1/convai/agents/{agent_id}/simulate-conversation/stream

ElevenLabs API

Simulates 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

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