API ReferenceTests

Cancel Suite Run

Beta

Cancel a suite run: every child run still pending or running is cancelled, which makes the suite’s derived status cancelled. Child runs that already produced a verdict or errored are left untouched. Idempotent on a terminal suite - returns it unchanged.

Authentication

AuthorizationBearer

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

Path parameters

suite_run_idstringRequired
Suite run ID.

Headers

Speechify-VersionstringOptional

Response

The suite run with its child runs.
idstring

Prefixed wire identifier (srun_<26 char Crockford base32>).

triggerenum

Which entry point created a suite run.

  • run_all - POST /v1/agents/{agent_id}/tests/runs.
  • batch - POST /v1/agents/tests/runs/batch.
  • resubmit - POST /v1/agents/tests/suite-runs/{suite_run_id}/resubmit.
statusenum

The one lifecycle vocabulary shared by every async job (batch calls, knowledge-base imports, agent-test runs, suite runs): pending → running → a terminal state.

  • pending - accepted but not yet executing (queued for a worker, or deferred to a future scheduled time).
  • running - actively executing.
  • completed - ran to conclusion. The single terminal-success verb. For a job that produces a pass/fail judgment (an agent-test run), this means it produced a verdict - read the separate verdict field for the judgment, not this status.
  • failed - could not complete (an infrastructure or input failure), distinct from a completed job whose verdict is failed.
  • cancelled - cancelled before reaching a natural terminal state.
totalinteger
Number of child runs in the suite.
completedinteger
Child runs that produced a verdict.
failedinteger

Child runs that could not execute (an infrastructure failure).

runninginteger
Child runs actively executing.
pendinginteger
Child runs queued, not yet executing.
cancelledinteger
Child runs cancelled.
resultsobject

Per-verdict breakdown among the completed child runs.

created_atdatetime
runslist of objects
agent_idstring or null

Prefixed agent_<crockford> id of the agent whose suite was run. Set for the run_all trigger; null for batch, which can span many agents.

agent_namestring or null

Display name of agent_id’s agent, resolved at read time. Null whenever agent_id is null, and on the suite run embedded in run/resubmit creation responses.

parent_suite_run_idstring or null

Set on a resubmit: the prefixed srun_<crockford> id of the suite run whose failed/errored tests this one re-ran. Null for run_all and batch.

verdictenum or null

The suite’s pass/fail judgment, present only when status is completed.

ended_atdatetime or null

Newest child-run completion; null until every child run is terminal.

config_overrideobject or null

The run-level config override this suite was run with, or null for an ordinary Run All / batch.

flow_version_idstring or null

The flow version (agent_versions row) this suite targeted, or null for the agent’s active / synthesized flow.

flow_version_numberinteger or null

Human-facing version number of flow_version_id; null when no version was targeted.

Errors

401
Unauthorized Error
404
Not Found Error