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`

All three share the same observability shape.

Run shape

Field	Notes
`id`	Stable run identifier
`kind`	`column`, `workflow`, `ingestion`
`status`	`queued`, `running`, `completed`, `succeeded`, `failed`, `paused`, `canceled`
`mode`	`smoke_test`, `dry_run`, `live` (see Modes)
`trigger`	What started it (user, schedule, event, webhook)
`items_total`	Items in scope
`items_succeeded`, `items_failed`, `items_pending`	Counts
`credits_used`, `credits_reserved`	Cost so far
`started_at`, `finished_at`	Timestamps
`web_url`	Deep-link to the timeline in the web app

Item shape

Field	Notes
`id`	Stable item identifier within the run
`row_id`	The table row, if applicable
`status`	`pending`, `running`, `succeeded`, `failed`, `retrying`, `skipped`
`attempt_count`	Retry attempts so far
`inputs`	Inputs passed to the producer
`outputs`	Producer output (provider payload, AI response, etc.)
`error`	Failure detail
`credits_used`	Per-item cost

Working with runs

oxygen runs list --json
oxygen runs get <run-id> --json
oxygen table-runs list --table <table-id> --json
oxygen table-runs get <run-id> --json
oxygen table-runs items <run-id> --json
oxygen table-runs provider-summary <run-id> --json     # per-provider breakdown
oxygen workflows runs --workflow <workflow-id> --json
oxygen workflows run <workflow-run-id> --json
oxygen workflows failures --json
oxygen observability events --json

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

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.

Cost accounting

Credits move through four states per run:

State	Trigger
Reserved	Run starts; estimated cost held against balance
Captured	Item succeeds with cost > 0
Released	Item fails before billing; reservation returned
Granted	Plan refill or top-up

See Billing for the credit ledger.

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