> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent run

> The agent-run resource: read runs, control them with pause/resume/cancel/rollback actions, and submit their execution receipts.

An agent run records one execution by an agent: status, cost, tokens,
timing, and linkage to the initiative it served. Runs are created by the OrgX
execution system — spawning through Mission Control, the MCP `orgx_spawn` tool,
or connected clients — not by a direct REST insert. The v1 API controls a known
run and submits its receipt; the compatibility adapter provides API-key reads.

<Note>
  Naming crosswalk: this resource is `run` on the compatibility
  [`/api/entities`](/docs/api/entities/generic) surface. The v1 action route is the
  canonical API-key write surface.
</Note>

## Read

```bash theme={"dark"}
curl "https://useorgx.com/api/entities?type=run&status=running&initiative_id=2c6d3e4f-..." \
  -H "Authorization: Bearer $ORGX_API_KEY"
```

This is a compatibility read. New integrations should use a run ID returned by
the execution system, then call the v1 control route below.

Run rows carry: `id`, `title`, `summary`, `status`, `initiative_id`,
`primary_agent_id`, `cost_cents`, `token_count`, `started_at`,
`completed_at`, `created_at`, `workspace_id`, `metadata`. Add
`include_relationships=true` to embed run steps and run artifacts.

`status` values: `draft`, `planned`, `awaiting_approval`, `running`,
`blocked`, `paused`, `completed`, `failed`, `cancelled`, `archived`.

## Control — `POST /api/v1/runs/{runId}/actions/{action}`

API-key authenticated. `{action}` must be one of:

| Action     | Effect                                           |
| ---------- | ------------------------------------------------ |
| `pause`    | Pause a running run.                             |
| `resume`   | Resume a paused run.                             |
| `cancel`   | Cancel the run.                                  |
| `rollback` | Roll back to a checkpoint (send `checkpointId`). |

Optional body fields: `checkpointId`, `reason`.

```bash theme={"dark"}
curl https://useorgx.com/api/v1/runs/9c7b1d68-2c5c-6d6b-1a8e-5c4f2c0c5b4d/actions/pause \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Waiting on the pricing decision"}'
```

`POST /api/v1/lifecycle` with `level: "run"` offers the same control verbs
(`pause`, `resume`, `retry`, `cancel`) plus `retry`, with
initiative-ownership checks.

## Direct status writes are blocked

`PATCH /api/entities` on a run rejects `status`, `started_at`,
`completed_at`, and `cancelled_at` with `403` — run state changes must go
through the action routes above so control history stays accurate. Other run
fields (title, summary, metadata) are patchable.

## All operations on this resource

| Operation                  | Method + path                                 | Auth                  | Notes                                                                                                                                                                  |
| -------------------------- | --------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| List / get (compatibility) | `GET /api/entities?type=run`                  | API key               | Filters: `status`, `initiative_id`, `search`, `ids`.                                                                                                                   |
| List (app)                 | `GET /api/v1/runs`                            | Session               | Web-app view of your requested runs.                                                                                                                                   |
| Get one (app)              | `GET /api/v1/runs/{runId}`                    | Session               | Returns `{ run, receipt, steps, blocker }`.                                                                                                                            |
| Control                    | `POST /api/v1/runs/{runId}/actions/{action}`  | API key               | `pause`, `resume`, `cancel`, `rollback`.                                                                                                                               |
| Checkpoints                | `GET`/`POST /api/v1/runs/{runId}/checkpoints` | API key               | List or create checkpoints; restore via the `rollback` action.                                                                                                         |
| Lifecycle                  | `POST /api/v1/lifecycle` with `level: "run"`  | API key               | `pause`, `resume`, `retry`, `cancel`.                                                                                                                                  |
| Submit receipt             | `POST /api/v1/runs/{runId}/receipt`           | Scoped key or session | Requires a key with the `gateway:drive` scope (plugin install keys). One receipt per run; retries return the original.                                                 |
| Create                     | Not exposed as a direct insert                | —                     | Runs are created by execution: spawn via MCP `orgx_spawn`, Mission Control, or connected clients. `POST /api/v1/spawn` is a pre-flight gate check and creates nothing. |
| Delete                     | Not exposed                                   | —                     | `cancel` then `archived` status is the terminal path.                                                                                                                  |

## Where the IDs come from

| Field           | Obtain it from                                                                       |
| --------------- | ------------------------------------------------------------------------------------ |
| `runId`         | Returned by the execution system or a compatibility run read                         |
| `checkpointId`  | `GET /api/v1/runs/{runId}/checkpoints` (API key)                                     |
| `initiative_id` | [`POST /api/v1/initiatives`](/docs/api/entities/initiative) response `data.initiativeId`  |
| blocker `id`    | `GET /api/entities?type=blocker` rows (blockers are scoped through their parent run) |

## Related: blockers

Runs raise blockers (`type: "blocker"` on the compatibility surface) when they need
a human. Blocker rows are read-only through the compatibility REST adapter: they carry `status`
(`open`, `resolved`, `dismissed`), `run_id`, `decision_id`, and resolution
fields, and they close through their own resolve/dismiss lifecycle rather
than direct PATCH writes.

## MCP equivalents

`orgx_spawn` guards, classifies, and dispatches new runs; `orgx_act` and the
MCP lifecycle tools pause and resume them; `orgx_emit_activity`,
`orgx_request_attention`, and `orgx_emit_execution_graph` stream run
telemetry that has no public REST write equivalent today.