Skip to main content
POST
curl

Authorizations

Authorization
string
header
required

An API key (sig_...), or a session token from the web app.

Path Parameters

agentId
string<uuid>
required

The agent's id.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

Body

application/json
version
integer
required

The agent version to play. Its configuration must be stored, so its tools can be mocked.

Required range: x >= 0
testSetId
string<uuid>

Run every test in this set. Send this or testIds.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

testIds
string<uuid>[]

Run these tests, in this order. Send this or testSetId. Every id must be one of this agent's tests: an unknown id is 404 tests_not_found and an archived one 400 tests_archived, both naming the ids, and nothing runs.

Minimum array length: 1
Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
personas
string[]

Persona slugs (GET .../personas, runnable ones); each test runs once per persona. @source is each test's own caller. Absent: each test's own.

Minimum array length: 1
Minimum string length: 1
repeats
enum<number>

3: every cell runs three times and reports how many of them passed. Absent: once, and again on a failure; guard tests always run three times.

Available options:
3
shadowAgentId
string<uuid>

Play this shadow copy (POST .../shadows) instead of the version itself; the version must be the one it was cloned from.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

goalId
string<uuid>

The goal this run works toward; its cost is counted on the goal. The in-app copilot must send the goal of a plan a person approved.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

draftId
string<uuid>

The draft this run is for, recorded only. A draft's test through POST .../drafts/{draftId}/test is what counts toward publishing.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

phoneCalls
boolean

true: tests that need a phone call (hearing or speaking issues) are played as real calls on the test's agent copy, at most 5 minutes each and never retried, instead of being skipped. Each is a call on your Retell account. Cannot be combined with repeats. Each call holds 30 credits while it runs and is charged 6 credits at least, then 1 per 10 seconds. When the calls' holds and the run's other tests would not fit the workspace's credits left, the run is refused with quota_exceeded (metric credits) and nothing is queued.

Response

The run, queued.

object
enum<string>
required
Available options:
run
id
string<uuid>
required
Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

status
enum<string>
required

queued, running, then complete, refused (budget) or failed. An automatic run over the budget waits in awaiting_approval for a person.

Available options:
queued,
awaiting_approval,
running,
complete,
refused,
failed
message
string | null
required

The latest status message: what the budget covered, or why it refused or failed.

kind
enum<string>
required

A calibration run plays each test several times to decide whether it gates.

Available options:
run,
calibration
trigger
enum<string> | null
required

Who started it: a person, SignalMD on a new version, or an API key.

Available options:
manual,
auto,
ci,
null
version
integer
required

The agent version played.

testSetId
string<uuid> | null
required
Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

testIds
string<uuid>[]
required

The tests requested, in order.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
personas
string[] | null
required

The personas requested; null means each test's own caller.

repeats
enum<number> | null
required

3: every cell runs three times and reports how many of them passed.

Available options:
3
shadowAgentId
string<uuid> | null
required

Set when the run played a shadow copy of the version.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

goalId
string<uuid> | null
required

The goal this run worked toward.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

draftId
string<uuid> | null
required

The draft whose shadow copy this run played.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"

draftScope
enum<string> | null
required

Set on a draft's test: an attempt, or the full accepted suite (what a publish through the API needs).

Available options:
attempt,
full_suite,
null
phoneCalls
boolean
required

True when tests that need a phone call were played as real calls rather than skipped.

progress
object
required

Cells finished of cells to play.

cells
object
required

Fewer runnable than requested means the budget covered part of the run; the rest are not run.

summary
object
required
Example:
cost
object
required

Estimated spend.

spend
object
required

What the run spent in one place; a goal's model spend is on GET .../goals/{goalId}.

phoneMinutes
object | null
required

Test minutes this run's phone calls count against the plan, from the same allowance its simulated tests use. Null when the run plays no phone calls.

approvedAt
string<date-time> | null
required

When a person approved an automatic run that was over the budget.

Example:

"2026-10-02T14:03:07.120Z"

createdBy
string | null
required

Who started it: a user id, or key: for an API key.

createdAt
string<date-time>
required
Example:

"2026-10-02T14:03:07.120Z"

updatedAt
string<date-time>
required
Example:

"2026-10-02T14:03:07.120Z"

estimate
object
required

What was checked when the run was accepted.