Run Tests (Targeted) | SpeechifyAI API

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

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

Run a chosen set of tests against a target agent, bound at run time. The tests are not attached to the agent, so the same set can run against another agent variant in a second call (A/B) and, once agent versioning ships, against a pinned version (version-pinned regression). Every child run records the resolved target on the returned suite run. Total runs are capped at 100 per call; poll GET /v1/agents/tests/runs/{test_run_id} for each.

Run a chosen set of tests against a target agent, bound at run time. The tests are not attached to the agent, so the same set can run against another agent variant in a second call (A/B) and, once agent versioning ships, against a pinned version (version-pinned regression). Every child run records the resolved target on the returned suite run. Total runs are capped at 100 per call; 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.

test_idslist of stringsRequired

Prefixed test_<crockford> ids to run. De-duplicated, so a repeated id runs once.

targetobjectRequired

The agent a targeted run binds to at run time. agent_id is required. version and tag pin a specific agent version once agent versioning ships; supplying either today returns 400, so agent-id targeting works now and version/tag light up later without a wire change.

config_overrideobjectOptional

A run-level config override applied to every test in a Run All. Layered on top of the agent’s stored config for the duration of the suite run, so the whole suite can be validated against a proposed prompt / model / toolbelt without editing any test. An absent field leaves the agent’s value untouched; a run-level override wins over a deprecated per-test system_prompt_override / model_override.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-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.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-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. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

Runs queued.

runslist of objects

suite_runobject or nullOptional

The suite run grouping the queued runs.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error