The run management tools family covers the durable run lifecycle. Skill-backed tools execute as durable runs — persistent state machines that survive server restarts, stream events as they progress, and produce artifacts on completion. The agent creates runs with run_skill, inspects them with get_run, polls for new events with subscribe_run, and cancels them with cancel_run.
The run state machine
Every durable run moves through a fixed state machine:
draft → queued → running → succeeded
→ failed
→ cancelled
| State | Description |
|---|
draft | The run has been created but not yet queued. The agent can still modify inputs. |
queued | The run is waiting for a worker. Inputs are frozen. |
running | A worker has picked up the run and is executing the skill. Events stream in real time. |
succeeded | The run completed successfully. Artifacts are available. |
failed | The run failed. The error field on the run record contains details. |
cancelled | The run was cancelled by the agent or the human. The reason field records why. |
succeeded, failed, and cancelled are terminal states. A run in a terminal state cannot be restarted — you must create a new run.
run_skill
Create a durable run for a skill. Returns a run_id immediately; the skill executes asynchronously. Poll with get_run or stream with subscribe_run for progress and results.
Arguments
| Argument | Type | Required | Description |
|---|
skill_id | string | Yes | The skill identifier (from search_skills). |
input | object | Yes | The skill input dict (validated against the skill’s input_schema). |
mode | string | No | Execution mode: sync (wait for completion, default for short skills) or async (return immediately). Default async. |
Return value
| Field | Type | Description |
|---|
run_id | string (UUID) | The durable run identifier. |
skill_id | string | The skill being run. |
status | string | Initial status (draft or queued). |
created_at | string (ISO 8601) | When the run was created. |
Example call
{
"skill_id": "congress_trades",
"input": { "symbol": "NVDA", "since": "2024-01-01" },
"mode": "async"
}
Example response
{
"run_id": "run_01HQKX2J3K4M5N6P7R8S9T0V3C",
"skill_id": "congress_trades",
"status": "queued",
"created_at": "2025-01-15T14:35:00.123Z"
}
get_run
Fetch the full run record — status, jobs, artifacts, and events. This is the polling endpoint. For long-running skills, call get_run periodically until status is terminal.
Arguments
| Argument | Type | Required | Description |
|---|
run_id | string | Yes | The run identifier. |
Return value
| Field | Type | Description |
|---|
run_id | string | The run identifier. |
skill_id | string | The skill being run. |
status | string | Current state of the run. |
input | object | The frozen input dict. |
output | object | null | The skill output, if the run succeeded. |
error | object | null | Error details, if the run failed. |
jobs | array | Sub-jobs (e.g. per-symbol fetches) with their own statuses. |
artifacts | array | Artifacts produced by the run (with artifact_id and uri). |
events | array | Chronological event log (state transitions, progress, logs). |
created_at | string | When the run was created. |
updated_at | string | When the run was last updated. |
Example call
{ "run_id": "run_01HQKX2J3K4M5N6P7R8S9T0V3C" }
Example response
{
"run_id": "run_01HQKX2J3K4M5N6P7R8S9T0V3C",
"skill_id": "congress_trades",
"status": "succeeded",
"input": { "symbol": "NVDA", "since": "2024-01-01" },
"output": {
"trades": [
{ "member": "Pelosi, Nancy", "symbol": "NVDA", "transaction_date": "2024-06-24", "type": "buy", "amount_range": "$1,000,001 - $5,000,000", "filing_date": "2024-07-01" }
]
},
"error": null,
"jobs": [
{ "job_id": "job_01", "step": "fetch_disclosures", "status": "succeeded", "duration_ms": 1240 }
],
"artifacts": [
{ "artifact_id": "art_01HQKX2J3K4M5N6P7R8S9T0V3D", "uri": "s3://doomberg-artifacts/run_01.../trades.json", "content_hash": "sha256:..." }
],
"events": [
{ "ts": "2025-01-15T14:35:00.123Z", "type": "run_created" },
{ "ts": "2025-01-15T14:35:00.500Z", "type": "run_queued" },
{ "ts": "2025-01-15T14:35:01.100Z", "type": "job_started", "job_id": "job_01" },
{ "ts": "2025-01-15T14:35:02.340Z", "type": "job_succeeded", "job_id": "job_01" },
{ "ts": "2025-01-15T14:35:02.500Z", "type": "run_succeeded" }
],
"created_at": "2025-01-15T14:35:00.123Z",
"updated_at": "2025-01-15T14:35:02.500Z"
}
subscribe_run
Poll for new events since a cursor. This is the efficient alternative to re-fetching the full run record on every poll. Pass the cursor returned by the previous subscribe_run call to get only events that arrived after that point.
Arguments
| Argument | Type | Required | Description |
|---|
run_id | string | Yes | The run identifier. |
cursor | string | No | An opaque cursor from a previous subscribe_run response. If omitted, returns all events from the start. |
Return value
| Field | Type | Description |
|---|
run_id | string | The run identifier. |
status | string | Current run status. |
events | array | Events that arrived after the cursor. |
cursor | string | The cursor to pass on the next call. |
done | boolean | true if the run is in a terminal state and no more events will arrive. |
Example call
{ "run_id": "run_01HQKX2J3K4M5N6P7R8S9T0V3C", "cursor": "evt_01HQKX2J3K4M5N6P7R8S9T0V3E" }
Example response
{
"run_id": "run_01HQKX2J3K4M5N6P7R8S9T0V3C",
"status": "succeeded",
"events": [
{ "ts": "2025-01-15T14:35:02.340Z", "type": "job_succeeded", "job_id": "job_01" },
{ "ts": "2025-01-15T14:35:02.500Z", "type": "run_succeeded" }
],
"cursor": "evt_01HQKX2J3K4M5N6P7R8S9T0V3F",
"done": true
}
When done is true, stop polling. The run is terminal and no further events will arrive. Fetch the final output with get_run if you haven’t already.
cancel_run
Cancel a queued or running run. The run transitions to cancelled and the worker stops processing. Already-produced artifacts are retained.
Arguments
| Argument | Type | Required | Description |
|---|
run_id | string | Yes | The run identifier. |
reason | string | No | A human-readable reason for the cancellation. Stored on the run record. |
Return value
| Field | Type | Description |
|---|
run_id | string | The run identifier. |
status | string | cancelled. |
cancelled_at | string (ISO 8601) | When the run was cancelled. |
reason | string | The reason provided. |
Example call
{ "run_id": "run_01HQKX2J3K4M5N6P7R8S9T0V3C", "reason": "User changed research direction." }
Example response
{
"run_id": "run_01HQKX2J3K4M5N6P7R8S9T0V3C",
"status": "cancelled",
"cancelled_at": "2025-01-15T14:36:00.000Z",
"reason": "User changed research direction."
}
A run in a terminal state (succeeded, failed, cancelled) cannot be cancelled. Calling cancel_run on a terminal run returns a run_already_terminal error.
Polling pattern
Create the run
Call run_skill with the skill_id and input. Get back a run_id.
Subscribe for events
Call subscribe_run with the run_id (no cursor). Process the initial events and save the cursor.
Poll until done
Call subscribe_run with the saved cursor on an interval (e.g. every 1–2 seconds). Stop when done is true.
Fetch the final output
Call get_run to read the output, artifacts, and full event log.
