Cancel Agent Run | SpeechifyAI API

{
  "id": "arun_01kr410dd3yrst4chn5kn0t78f",
  "agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
  "files": [
    {
      "id": "file_01kr41f8m2p7q3v9x0y1z2a3b4",
      "filename": "chart-4.png",
      "content_type": "image/png",
      "size_bytes": 48213,
      "kind": "ephemeral",
      "content_path": "/v1/files/file_01kr41f8m2p7q3v9x0y1z2a3b4/content",
      "created_at": "2026-09-04T09:14:09Z",
      "user_identity": "acme_user_42",
      "source": {
        "run_id": "arun_01kr410dd3yrst4chn5kn0t78f",
        "step": 4
      },
      "expires_at": "2026-09-18T09:14:09Z"
    }
  ],
  "status": "succeeded",
  "input": {
    "instruction": "Summarize the attached contract, list every renewal date, and chart the annual fee.",
    "max_turns": 8,
    "user_identity": "acme_user_42"
  },
  "created_at": "2026-09-04T09:14:02Z",
  "output": {
    "reply": "The contract renews on 1 March and auto-renews annually unless cancelled 30 days prior. The fee chart is attached.",
    "data": {
      "renewal_dates": [
        "2027-03-01"
      ]
    }
  },
  "usage": {
    "duration_ms": 8420,
    "input_tokens": 5310,
    "cached_input_tokens": 1200,
    "output_tokens": 412,
    "total_tokens": 5722,
    "cost_micro_usd": 13404,
    "rate_card_version": "2026-09-08",
    "models": [
      {
        "model": "gpt-5.6-terra",
        "input_tokens": 5310,
        "cached_input_tokens": 1200,
        "output_tokens": 412,
        "total_tokens": 5722,
        "cost_micro_usd": 13404
      }
    ]
  },
  "started_at": "2026-09-04T09:14:03Z",
  "ended_at": "2026-09-04T09:14:11Z"
}

Request cancellation. Idempotent: a queued run cancels immediately; a running run flips to canceling and settles at its next checkpoint; a terminal run is unchanged.

This endpoint is in beta: it is available to workspaces granted durable_runs_access, and every other workspace receives 402 durable_runs_not_in_plan.

Authentication

AuthorizationBearer

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

Path parameters

agent_idstringRequired

Agent id (prefixed external id, agent_...).

run_idstringRequired

Run id (prefixed external id, arun_...).

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.

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

The run after the cancel request.

idstring

Run id (prefixed external id, arun_...).

agent_idstring

The agent that ran. On a delegated child this is the member agent, not the manager.

fileslist of objects

The files this run’s own tool calls produced, in the order they were made: a picture from generate_image or edit_image, a chart from render_chart, a file run_code kept, a tool response that was not text. Each is the same object GET /v1/files/{file_id} returns, so content_path streams the bytes and source.step is the journal step of the tool call that made it, with no second lookup.

Always present. It grows while the run is going - the event stream carries each file on the step that produced it - and an empty list on a finished run means it produced nothing, never that the files are on another page. A run that failed or was cancelled after making a file still lists it. A file scoped to the run’s user_identity is listed here and is readable by a run acting for that same person, exactly as under /v1/files. A file deleted or expired since is no longer listed.

statusenum

Lifecycle: queued -> running -> succeeded | failed | canceled | expired. requires_action (a pending human approval) and canceling are transient. Terminal set: succeeded, failed, canceled, expired.

inputobject

The frozen request the run was created with.

created_atdatetime

When the run was accepted and queued.

project_idstring or nullOptionalformat: "^proj_[0-9a-hjkmnp-tv-z]{26}$"

The project this run belongs to; null when it belongs to none. Captured when the run was created, so it does not move if the agent later does.

outputobjectOptional

The run’s result, present only when status is succeeded.

errorobjectOptional

Present only when status is failed.

incomplete_reasonenumOptional

Why a non-failed run stopped short: max_turns_exhausted, budget_exhausted, or output_schema_violation (the agent never produced an object matching input.output_schema; output.reply keeps its prose and output.data is absent).

usageobjectOptional

What the run spent, present only once it has settled: wall-clock, the tokens summed across every step, the same tokens split per model, and what they cost at your plan’s rates. Written once at settle and never restated; the webhook payload carries the same values. input_tokens includes the cached reads and cached_input_tokens is that subset, so the two are never added. cost_micro_usd is an integer in millionths of a US dollar, computed from the rate card version named alongside it, and is informational: your invoice is authoritative. A delegated child run reports its own usage; the parent never sums it.

pending_actionobjectOptional

A human approval a run is durably parked on (present on AgentRun only while status is requires_action). Rendered VERBATIM for the approver - never a summary the agent wrote - so an injected agent cannot misrepresent what it is about to do. Resolve it with submitRun.

metadatamap from strings to stringsOptional

parent_run_idstringOptionalformat: "^arun_[0-9a-hjkmnp-tv-z]{26}$"

The run that delegated this one a sub-goal, absent on a root run. It is the upward half of lineage - what makes a child run of a member agent attributable to the team run that caused it (listRunChildren is the downward half).

started_atdatetimeOptional

When a worker picked the run up. Absent while queued; the gap between this and created_at is queue wait, not agent time.

ended_atdatetimeOptional

When the run settled. Present for every terminal status - succeeded, failed, canceled and expired alike - and absent otherwise.

Errors

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error