VOICE RUN: Execute evaluators against your agent using a real voice / phone / SIP call. This is the primary 'run your evaluators' endpoint for voice-mode testing. Requires telephony.phone_number configured on the agent (any provider).

Run-count math: total calls = len(scenarios) × frequency × max(1, len(personality_ids)) × max(1, len(test_profile_ids)). Each call is billed at the voice-simulation rate — check frequency carefully.

Concurrency: use concurrency_limit to cap parallel calls. Default: unbounded (subject to provider rate limits).

Scenario selection (pick one):

• scenarios — list of integer evaluator IDs (e.g. [101, 102])
• tags — select by tag
• folder_path — select by folder path (e.g. "Sales.Inbound"); requires project_id

Phone-number overrides:

• outbound_phone_number — override the number dialed
• agent_number — override the contact number the inbound agent receives calls on
• mode — same_number (all runs use one pair) vs different_numbers

When to use this vs others (pick the endpoint matching the agent's configured connection — check aiagents_retrieve):

• run_scenarios_text — text / SMS / chat mode; cheaper, no voice cost
• run_scenarios_with_websockets — each scenario carries its own websocket URL
• run_scenarios_pipecat — Pipecat/Daily.co WebRTC deployment

Personality override: personality_ids must be IDs that are already enabled for the agent's project. Check which are enabled via aiagents_retrieve → enabled_personalities field. To enable a new personality, call aiagents_partial_update with the updated enabled_personalities list before using it here. Note: enabling a personality applies project-wide, not just to one agent. Passing an ID that is not enabled returns ["Invalid personalities provided."].

Scheduled runs: to run on a recurring cron schedule, create a CronJob via POST /test_framework/v1/cron_jobs/ with execution_mode="voice" instead of looping this endpoint.

Polling for completion: the response is the result itself — read its top-level id (status: 'running'). Poll GET /test_framework/v1/results/{result_id}/ until status is completed, failed, timeout or cancelled. A result stays non-terminal until every run has ended, then becomes completed if any run completed — even if runs failed their checks or others errored. To gate, require success_runs_count == total_runs_count (failed_runs_count counts only completed runs that failed evaluation). There is no separate progress endpoint for runs. Check failed_reasons for infrastructure errors; check runs[run_id].error_message for per-run errors.

Outbound dial window: for outbound runs (agent inbound=false), your agent must dial the run's outbound_number before outbound_dial_window_closes_at (default 300s after the run reaches waiting_for_call / pending state). Dials received after that deadline are dropped and the run returns status: timeout.

{
  "runs": [
    {
      "number": "+11234567890",
      "inbound_number": "+11234567890"
    }
  ],
  "created_at": "2025-02-25T21:00:01.990052Z"
}