TEXT / SMS / CHAT RUN: Execute evaluators against your agent using text-only simulation (SMS, chat, or an agent-hosted websocket). Cheaper than voice — billed at the text-simulation rate. Requires a chat connection (provider.chat_agent_details) on the agent, or a websocket URL for self_hosted agents.

Run-count math: total conversations = len(scenarios) × frequency × max(1, len(personality_ids)) × max(1, len(test_profile_ids)).

Concurrency: use concurrency_limit to cap parallel conversations. 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

Websocket override: if the agent exposes a plain websocket URL for text, pass it as websocket_url — this bypasses the agent's standard text-readiness check. Pass websocket_headers (JSON object) to override connection headers for this run — merged over the agent's configured headers, with the per-run values winning.

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

• run_scenarios — real voice / phone / SIP call
• run_scenarios_with_websockets — each scenario carries its own websocket URL (bulk)
• run_scenarios_pipecat — Pipecat/Daily.co WebRTC deployment

self_hosted agents: agents with assistant_provider="self_hosted" require a websocket URL. Either pre-configure websocket_url on the agent, or pass it directly in this request. Without it, the run fails with ["Agent does not have a websocket URL"]. Passing websocket_url here changes the result's run_type to "WebSocket" instead of "Text".

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 cron schedule, create a CronJob via POST /test_framework/v1/cron_jobs/ with execution_mode="text" instead.

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.

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