POST

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

ElevenLabs playground

Simulates A Conversation

Credentials

ElevenLabs API key · sent as xi-api-key

Kept in this tab only. Requests go through apicheats.dev's same-origin proxy straight to api.elevenlabs.io; the proxy stores and logs nothing about them.

Path

agent_id · required · string The id of an agent. This is returned on agent creation.

Body application/json

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

3 body fields

simulation_specification · required · object — A specification that will be used to simulate a conversation between an agent and an AI user.
extra_evaluation_criteria · optional · object[] — A list of evaluation criteria to test
new_turns_limit · optional · integer — Maximum number of new turns to generate in the conversation simulation