Agent run

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.

Naming crosswalk: this resource is run on the compatibility /api/entities surface. The v1 action route is the canonical API-key write surface.

Read

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.

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` response `data.initiativeId`
blocker `id`	`GET /api/entities?type=blocker` rows (blockers are scoped through their parent run)

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.

Getting Started

Connect Your Tools

Agent Ops

Platform

Build with the API

REST API v1 Reference

Entity Reference

Content Studio API

MCP and Plugins

Resources

Read

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

Direct status writes are blocked

All operations on this resource

Where the IDs come from

MCP equivalents

​Read

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

​Direct status writes are blocked

​All operations on this resource

​Where the IDs come from

​Related: blockers

​MCP equivalents

Read

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

Direct status writes are blocked

All operations on this resource

Where the IDs come from

Related: blockers

MCP equivalents