Runs

A run is the persistent record of one execution: a column applied to N rows, a workflow fire, an ingestion of a provider search page. Inside a run are items — one per row, per call, or per step.

Three run types

Type	Created by
Column run (`table-runs`)	`oxygen columns run` or `oxygen table-runs create`
Workflow run	`oxygen workflows call`, a schedule, a webhook, or an event trigger
Ingestion run (`table-ingestions`)	`oxygen table-ingestions create-tool-page`

Statuses

The run families do not share a status vocabulary, and the API rejects a value outside its own set.

	Values
Column run	`queued`, `running`, `paused`, `completed`, `completed_with_errors`, `failed`, `canceling`, `canceled`
Ingestion run	the same set without `paused` — an ingestion cannot be paused
Column / ingestion item	`pending`, `leased`, `completed`, `failed`, `skipped`, `canceled`
Workflow run	`queued`, `running`, `waiting`, `awaiting_approval`, `completed`, `failed`, `canceling`, `canceled`

waiting is not a failure: the run is parked on an external condition it did not cause and cannot retry out of — today, a provider's exhausted daily quota — and resumes when that condition clears. Sequence actions use their own deferral and legacy-recovery model; see Recovering old provider-capacity failures.

A column run also carries its selection, maxCredits, creditsReserved, creditsUsed, per-status counts, provider-error rollups, and the worker lease that claimed it. Each item carries attemptCount, readyAt, skippedReason, its last error, and its output. A workflow run additionally records the mode it fired in — see Modes.

Every run response carries web_url, the deep-link to that run's timeline in the web app: /tables/<table-id>/runs/<run-id> for a column run, /workflows/<workflow-id>/runs/<run-id> for a workflow run.

Working with runs

oxygen runs list --json
oxygen runs get <run-id> --json                        # summary + event stream
oxygen table-runs get <run-id> --json
oxygen table-runs items <run-id> --status failed --json
oxygen table-runs provider-summary <run-id> --json     # per-provider attempts and credit capture/release
oxygen workflows run <workflow-run-id> --json
oxygen workflows failures --json

Workspace-wide lenses across every primitive live in Observability. The full command surface is in the CLI reference.

Controlling an in-flight run

oxygen table-runs pause <run-id> --json
oxygen table-runs resume <run-id> --json
oxygen table-runs cancel <run-id> --json
oxygen workflows cancel <run-id> --json

Retrying failures

Per-item retry is built in. Only failed items re-execute:

oxygen table-runs retry-failed <run-id> --json
oxygen table-ingestions retry-failed <run-id> --json

If a table item failed with an unconfirmed external effect, the first command stops with effect_unknown_approval_required and returns the exact affected count plus a bounded item, row, step, and effect-context sample. Inspect all failed items and verify each destination first. Only when a human has confirmed another execution is safe, acknowledge that separate risk explicitly:

oxygen table-runs retry-failed <run-id> --approved-effect-unknown --json

This approval is recorded in the run event stream. Never add the flag to an automatic retry loop.

Debugging a failed run

oxygen runs get <run-id> --json — overall status and totals.
oxygen table-runs items <run-id> --status failed --json — failed items only.
For a failed item with a row: oxygen cells inspect <table-id> <row-id> <column> --json — full provider error and inputs (see Cells).
Fix the input or change provider. Then oxygen table-runs retry-failed <run-id> --json. For effect_unknown, verify the external destination and use the explicit acknowledgement above only if replay is safe.

Cost accounting

A run reserves credits against the balance when it starts, captures on each item that succeeds with a cost, and releases the unused remainder. Every entry and its transaction type is listed in the pricing reference; oxygen table-runs provider-summary <run-id> --json shows the capture/release split for one run.

Cells — per-cell view of what one item produced.
Triggers — what started this run.
Approvals — what blocked a live run waiting on input.

On this page