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

/v1/convai/agents/{agent_id}/run-tests

ElevenLabs API

Run 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

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"
    }
  ]
}