Runs

Inspect the current run

runs.get reads one durable run and the first page of its steps. It returns the run envelope rather than starting the capability again. Check its status and state version before you take a follow-up action.

Read all step pages

runs.events returns another page from the same step graph. Its completed and incomplete arrays contain only that page, with next_cursor and has_more telling you whether to continue. This read is free, synchronous, and does not rerun or alter work.

Cancel carefully

runs.cancel needs the state version from a run read. It stops queued and blocked steps from starting, but a step already executing finishes. Completed work remains completed and spent credits are not refunded. The returned status can still be running, reconciling, or partially completed.

Use the Run as the execution record

A Run is the durable record for accepted work that has a lifecycle beyond one response. It separates the request you made from steps that have completed, remain blocked, or can no longer start after cancellation. Use the Run when you need to report what happened without rerunning a capability and creating duplicate work.

Architect can read Runs while it works and presents its plan as a checklist in the app. The CLI, MCP, and REST use the same Runs controls, so a Run id and state version carry the same meaning across surfaces. A returned web_url can open an app object, but the Run id remains the identifier for the next Runs call.

Read the current Run before asking whether work succeeded. A capability can accept a request before every step finishes, especially when its contract records durable work. The status, completed array, incomplete array, and cursor fields are the evidence for the lifecycle rather than a guess based on the original command.

Handle partial work deliberately

Cancellation stops queued and blocked steps from starting, but it does not reverse completed work or interrupt a step already executing. That is why the cancellation result can still show running, reconciling, or partially completed state. Read the Run again after cancellation and identify which steps completed before deciding what should happen next.

Credits already spent are not refunded by cancelling a Run. For a live action that can create a provider effect, inspect the target object or external result as well as the Run state. This distinction matters for Sequences, social publishing, and Inbox replies, where a completed step can have reached someone outside the workspace.

There is no generic run resume command. Do not invent a state version or retry a stale cancellation, because the Run read is the source for the version runs.cancel needs. A table run checkpoint is a different capability, tables.table_runs.resume, reached with dreamstate tools run.

When it goes wrong

If a Run does not show every step in the first response, call runs.events with the same Run id and follow next_cursor while has_more is true. Do not interpret one page as the entire graph when the cursor says another page exists. The events read is free and synchronous, and it does not rerun work.

If cancellation cannot use the current version, fetch runs.get again before retrying. The CLI reads the state version from the Run response and tells you to pass it when it cannot find a valid value. This protects a newer Run state from an old cancellation request.

If a Run points to an external operation, inspect both the Run and the destination surface. A completed request does not tell you more than the capability result does about a later scheduled delivery or a separate provider state. Keep the Run id with the related Workbook, Sequence, post, or thread while you investigate.