Run Tests (Batch) | SpeechifyAI API

curl -X POST https://api.speechify.ai/v1/agents/tests/runs/batch \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "entries": [
    {
      "test_id": "test_01ky612y9cb7dbaj638x46msxv",
      "agent_id": "agent_01HS4X9VBCDEF1234567890AB"
    }
  ]
}'

{
  "runs": [
    {
      "id": "run_01kpvdq02cbtxqqsca60m5scng",
      "test_id": "test_01jqr8x9zg5k2m3n4p5q6r7s8t",
      "agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
      "status": "pending",
      "created_at": "2026-06-24T18:03:11Z",
      "verdict": "passed",
      "started_at": "2026-06-24T18:03:11Z",
      "ended_at": "2026-06-24T18:03:11Z",
      "result": {
        "test_type": "reply",
        "passed": true,
        "rationale": "The agent greeted Alice by name as required.",
        "duration_ms": 1240,
        "reply": {
          "agent_response": "Hi Alice! How can I help you today?",
          "passed": true,
          "rationale": "Response contains the caller's name.",
          "score": 0.95,
          "duration_ms": 1240
        },
        "tool_call": null,
        "simulation": null
      },
      "error": "example"
    }
  ],
  "suite_run": {
    "id": "srun_01kpvdq02cbtxqqsca60m5scng",
    "trigger": "run_all",
    "status": "pending",
    "total": 10,
    "completed": 7,
    "failed": 1,
    "running": 1,
    "pending": 1,
    "cancelled": 1,
    "results": {
      "passed": 1,
      "failed": 1
    },
    "created_at": "2026-06-24T18:03:11Z",
    "agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
    "agent_name": "example",
    "parent_suite_run_id": "parent_suite_run_01jqr8x9zg5k2m3n4p5q6r7s8t",
    "verdict": "passed",
    "ended_at": "2026-06-24T18:03:11Z",
    "config_override": {
      "prompt": "example",
      "model": "gpt-4o",
      "tool_ids": []
    },
    "flow_version_id": "fver_01arz3ndektsv4rrffq69g5fav",
    "flow_version_number": 1
  }
}

Queue runs for every (test, agent) pair in the body. Entries without an agent_id fan out to every agent the test is attached to. Total expanded runs are capped at 100 per call. Each entry in the response is a queued run; poll GET /v1/agents/tests/runs/{test_run_id} for each.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.

entrieslist of objectsRequired

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

Runs queued.

runslist of objects

suite_runobject or null

The suite run grouping the queued runs.

Errors

400

Bad Request Error

401

Unauthorized Error

409

Conflict Error