POST
/v1/convai/agents/{agent_id}/run-tests
ElevenLabs APIRun Tests On The Agent
- 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
→ 219 tokens · Vary: Accept
→ 219 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/run-tests' \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "tests": [ { "test_id": "string", "workflow_node_id": "string", "root_folder_id": "string", "root_folder_name": "string" } ], "agent_config_override": { "conversation_config": { "asr": { "keywords": [ "hello", "world" ], "provider": "scribe_realtime", "quality": "high", "user_input_audio_format": "pcm_16000" }, "turn": { "interruption_ignore_term_languages": [], "interruption_ignore_terms": [], "merge_with_default_ignore_terms": false, "mode": "turn", "retranscribe_on_turn_timeout": false, "silence_end_call_timeout": -1, "soft_timeout_config": { "message": "Hhmmmm...yeah.", "timeout_seconds": -1 }, "speculative_turn": false, "spelling_patience": "auto", "transcribe_on_disabled_interruptions": false, "turn_eagerness": "normal", "turn_model": "turn_v3", "turn_timeout": 7 }, "tts": { "agent_output_audio_format": "pcm_16000", "model_id": "eleven_turbo_v2", "optimize_streaming_latency": 3, "pronunciation_dictionary_locators": [], "similarity_boost": 0.8, "speed": 1, "stability": 0.5, "voice_id": "cjVigY5qzO86Huf0OWal" }, "conversation": { "client_events": [ "audio", "interruption" ], "max_duration_seconds": 600 }, "language_presets": {}, "vad": { "background_voice_detection": false }, "agent": { "disable_first_message_interruptions": false, "first_message": "Hello, how can I help you today?", "language": "en" } }, "platform_settings": { "evaluation": { "criteria": [ { "id": "[recursive or deeply nested schema]", "name": "[recursive or deeply nested schema]", "type": "[recursive or deeply nested schema]", "conversation_goal_prompt": "[recursive or deeply nested schema]", "use_knowledge_base": "[recursive or deeply nested schema]", "scope": "[recursive or deeply nested schema]", "llm": "[recursive or deeply nested schema]", "scoring_mode": "[recursive or deeply nested schema]", "max_score": "[recursive or deeply nested schema]", "score_instructions": "[recursive or deeply nested schema]" } ] }, "widget": { "custom_avatar_path": "https://example.com/avatar.png", "language_selector": false }, "data_collection": {}, "data_collection_scopes": {}, "analysis_items": { "evaluation_criteria": [ { "source": "[recursive or deeply nested schema]", "analysis_item_id": "[recursive or deeply nested schema]", "version_id": "[recursive or deeply nested schema]", "additional_version_ids": "[recursive or deeply nested schema]", "scope": "[recursive or deeply nested schema]", "weight": "[recursive or deeply nested schema]" } ], "data_collection": [ { "source": "[recursive or deeply nested schema]", "analysis_item_id": "[recursive or deeply nested schema]", "version_id": "[recursive or deeply nested schema]", "scope": "[recursive or deeply nested schema]" } ] }, "overrides": { "custom_llm_extra_body": true, "enable_conversation_initiation_client_data_from_webhook": true, "enable_procedure_ids_from_client": true, "enable_starting_workflow_node_id_from_client": true }, "workspace_overrides": { "conversation_initiation_client_data_webhook": { "request_headers": { "Content-Type": "application/json" }, "url": "https://example.com/webhook" }, "webhooks": { "post_call_webhook_id": "string", "events": [ "[recursive or deeply nested schema]" ], "transcript_format": "json", "send_audio": true } }, "testing": { "attached_tests": [ { "environment": "staging", "test_id": "test_123", "workflow_node_id": "node_abc" }, { "test_id": "test_456" } ], "referenced_tests_ids": [ "test_123", "test_456" ] }, "archived": false, "guardrails": { "version": "1", "focus": { "is_enabled": false }, "prompt_injection": { "is_enabled": false }, "content": { "execution_mode": "streaming", "config": { "sexual": "[recursive or deeply nested schema]", "violence": "[recursive or deeply nested schema]", "harassment": "[recursive or deeply nested schema]", "self_harm": "[recursive or deeply nested schema]", "profanity": "[recursive or deeply nested schema]", "religion_or_politics": "[recursive or deeply nested schema]", "medical_and_legal_information": "[recursive or deeply nested schema]" }, "trigger_action": { "type": "[recursive or deeply nested schema]" } }, "moderation": { "execution_mode": "streaming", "config": { "sexual": "[recursive or deeply nested schema]", "violence": "[recursive or deeply nested schema]", "violence_graphic": "[recursive or deeply nested schema]", "harassment": "[recursive or deeply nested schema]", "harassment_threatening": "[recursive or deeply nested schema]", "hate": "[recursive or deeply nested schema]", "hate_threatening": "[recursive or deeply nested schema]", "self_harm_instructions": "[recursive or deeply nested schema]", "self_harm": "[recursive or deeply nested schema]", "self_harm_intent": "[recursive or deeply nested schema]", "sexual_minors": "[recursive or deeply nested schema]" } }, "custom": { "config": { "configs": "[recursive or deeply nested schema]" } } }, "summary_language": "string", "auto_translate_transcript_to_app_language": true, "auth": { "allowlist": [ { "hostname": "https://example.com" } ], "enable_auth": true, "require_origin_header": true, "shareable_token": "1234567890" }, "call_limits": { "agent_concurrency_limit": -1, "bursting_enabled": true, "daily_limit": 100000 }, "privacy": { "apply_to_existing_conversations": false, "delete_audio": false, "delete_transcript_and_pii": false, "record_voice": true, "retention_days": -1, "zero_retention_mode": false }, "trust_context": "unknown", "analysis_llm": "gpt-4o-mini", "topic_discovery": {}, "sentiment_analysis": {}, "alerting": { "monitor_configs": {}, "auto_resolve_after_inactive_minutes": 0, "notifiers": [ { "type": "[recursive or deeply nested schema]", "webhook_id": "[recursive or deeply nested schema]" } ] } }, "workflow": { "edges": { "entry_to_tool_a": { "forward_condition": { "condition": "Tool A condition" }, "source": "entry_node", "target": "tool_node_a" }, "start_to_entry": { "forward_condition": {}, "source": "start_node", "target": "entry_node" }, "tool_a_to_failure": { "forward_condition": { "successful": false }, "source": "tool_node_a", "target": "failure_node" }, "tool_a_to_tool_b": { "forward_condition": { "successful": true }, "source": "tool_node_a", "target": "tool_node_b" }, "tool_b_to_agent_transfer": { "forward_condition": {}, "source": "tool_node_b", "target": "success_transfer" }, "tool_b_to_conversation": { "forward_condition": { "condition": "Conversation condition" }, "source": "tool_node_b", "target": "success_conversation" }, "tool_b_to_end": { "forward_condition": { "condition": "End condition" }, "source": "tool_node_b", "target": "success_end" }, "tool_b_to_phone": { "forward_condition": { "expression": { "children": [ { "name": "force_phone_transfer" }, { "prompt": "Phone condition", "value_schema": { "description": "Phone condition", "type": "boolean" } }, { "left": { "name": "mode" }, "right": { "value": "dev" } } ] } }, "source": "tool_node_b", "target": "success_phone" } }, "nodes": { "entry_node": { "conversation_config": {}, "edge_order": [ "entry_to_tool_a" ], "label": "Entry" }, "failure_node": { "conversation_config": {}, "label": "Failure" }, "start_node": { "edge_order": [ "start_to_entry" ] }, "success_conversation": { "conversation_config": {}, "label": "Success A" }, "success_end": {}, "success_phone": { "transfer_destination": { "phone_number": "+1234567890" } }, "success_transfer": { "agent_id": "success_transfer_agent" }, "tool_node_a": { "edge_order": [ "tool_a_to_failure", "tool_a_to_tool_b" ], "tools": [ { "tool_id": "tool_a" }, { "tool_id": "tool_b" } ] }, "tool_node_b": { "edge_order": [ "tool_b_to_conversation", "tool_b_to_end", "tool_b_to_phone", "tool_b_to_agent_transfer" ], "tools": [ { "tool_id": "tool_a" } ] } } } }, "branch_id": "string", "repeat_count": 1}'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. |
| tests | body | object[] | Yes | List of tests to run on the agent |
| agent_config_override | body | object | No | Configuration overrides to use for testing. If not provided, the agent's default configuration will be used. |
| branch_id | body | string | No | ID of the branch to run the tests on. If not provided, the tests will be run on the agent's main branch. |
| repeat_count | body | integer | No | Number of times to run each test. When greater than 1, results are grouped and summarized. |
Response 200 OK
{
"id": "string",
"agent_id": "string",
"branch_id": "string",
"created_at": 0,
"folder_id": "string",
"repeat_count": 1,
"bucketing_status": "pending",
"result_groups": [
{
"test_id": "string",
"test_name": "string",
"workflow_node_id": "string",
"buckets": [
{
"test_run_ids": [
"[recursive or deeply nested schema]"
],
"title": "string",
"reason": "string",
"status": "pending"
}
]
}
],
"test_runs": [
{
"test_run_id": "string",
"test_info": {
"from_conversation_metadata": {
"conversation_id": "string",
"agent_id": "string",
"branch_id": "string",
"workflow_node_id": "string",
"original_agent_reply": []
},
"dynamic_variables": {},
"chat_history": [
{
"role": "[recursive or deeply nested schema]",
"agent_metadata": "[recursive or deeply nested schema]",
"message": "[recursive or deeply nested schema]",
"multivoice_message": "[recursive or deeply nested schema]",
"tool_calls": "[recursive or deeply nested schema]",
"tool_results": "[recursive or deeply nested schema]",
"feedback": "[recursive or deeply nested schema]",
"llm_override": "[recursive or deeply nested schema]",
"producing_llm": "[recursive or deeply nested schema]",
"time_in_call_secs": "[recursive or deeply nested schema]",
"conversation_turn_metrics": "[recursive or deeply nested schema]",
"rag_retrieval_info": "[recursive or deeply nested schema]",
"llm_usage": "[recursive or deeply nested schema]",
"interrupted": "[recursive or deeply nested schema]",
"ignored_as_backchannel": "[recursive or deeply nested schema]",
"original_message": "[recursive or deeply nested schema]",
"reasoning": "[recursive or deeply nested schema]",
"source_medium": "[recursive or deeply nested schema]",
"source_event_id": "[recursive or deeply nested schema]",
"used_static_kb_document_ids": "[recursive or deeply nested schema]",
"user_identifier": "[recursive or deeply nested schema]",
"id": "[recursive or deeply nested schema]",
"triggered_guardrails": "[recursive or deeply nested schema]"
}
],
"conversation_initiation_source": "unknown",
"environment": "string",
"type": "llm",
"success_condition": "",
"success_examples": [
{
"response": "[recursive or deeply nested schema]",
"type": "[recursive or deeply nested schema]"
}
],
"failure_examples": [
{
"response": "[recursive or deeply nested schema]",
"type": "[recursive or deeply nested schema]"
}
]
},
"test_invocation_id": "string",
"agent_id": "string",
"branch_id": "string",
"workflow_node_id": "string",
"status": "pending",
"agent_responses": [
{
"role": "user",
"agent_metadata": {
"agent_id": "[recursive or deeply nested schema]",
"branch_id": "[recursive or deeply nested schema]",
"workflow_node_id": "[recursive or deeply nested schema]",
"version_id": "[recursive or deeply nested schema]"
},
"message": "string",
"multivoice_message": {
"parts": "[recursive or deeply nested schema]"
},
"tool_calls": [
"[recursive or deeply nested schema]"
],
"tool_results": [
"[recursive or deeply nested schema]"
],
"feedback": {
"score": "[recursive or deeply nested schema]",
"time_in_call_secs": "[recursive or deeply nested schema]"
},
"llm_override": "string",
"producing_llm": "string",
"time_in_call_secs": 0,
"conversation_turn_metrics": {
"metrics": "[recursive or deeply nested schema]",
"convai_asr_provider": "[recursive or deeply nested schema]",
"convai_tts_model": "[recursive or deeply nested schema]",
"convai_tts_cascade": "[recursive or deeply nested schema]"
},
"rag_retrieval_info": {
"chunks": "[recursive or deeply nested schema]",
"embedding_model": "[recursive or deeply nested schema]",
"retrieval_query": "[recursive or deeply nested schema]",
"rag_latency_secs": "[recursive or deeply nested schema]",
"used_chunk_ids": "[recursive or deeply nested schema]"
},
"llm_usage": {
"model_usage": "[recursive or deeply nested schema]"
},
"interrupted": false,
"ignored_as_backchannel": false,
"original_message": "string",
"reasoning": [
"[recursive or deeply nested schema]"
],
"source_medium": "audio",
"source_event_id": 0,
"used_static_kb_document_ids": [
"[recursive or deeply nested schema]"
],
"user_identifier": "string",
"id": "string",
"triggered_guardrails": [
"[recursive or deeply nested schema]"
]
}
],
"test_id": "string",
"test_name": "Unknown Test",
"condition_result": {
"result": "success",
"rationale": {
"messages": [
"[recursive or deeply nested schema]"
],
"summary": ""
}
},
"last_updated_at_unix": 0,
"metadata": {
"workspace_id": "string",
"test_name": "string",
"ran_by_user_email": "string",
"test_type": "llm"
},
"root_folder_id": "string",
"root_folder_name": "string",
"environment": "string"
}
]
}