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

POST /v1/convai/agents/{agent_id}/simulate-conversation/stream — ElevenLabs API

ElevenLabs API

Simulates 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

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

null
Get a free ElevenLabs API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.