Runs

A run is Everyn's durable record of work. It records which job spec version was used, which dataset rows were selected, what happened to each row, which outputs or failures were produced, which events were emitted, and what artifacts can be exported.

Runs are how Everyn makes AI work inspectable. The point is not only to get generated values back; the point is to know what was attempted, what succeeded, what failed, what it cost, and what can safely happen next.

Lifecycle and inspection

Lifecycle

Stage	What it means	Next action
Draft	The run record exists but has not started execution.	Confirm scope, job spec version, and approval.
Queued or running	Everyn is processing selected rows.	Watch progress, events, and early failures.
Succeeded	Execution reached a successful terminal state.	Inspect outputs, usage, and export readiness.
Failed	The run reached a terminal failure state.	Inspect failures and decide whether retry is appropriate.
Canceled	Work was stopped before normal completion.	Inspect partial state before creating new work.

Terminal runs and terminal rows are not reopened. New work creates a new run.

Sample runs and full runs

A sample run is a limited run, usually over a small row scope. It should prove that the job spec, output schema, selected model, and quality bar make sense before broader spend.

A full run applies the approved job spec version to the larger intended scope. Full-run approval should reference the sample evidence, expected output fields, known caveats, and usage or cost estimate when available.

Inspection checklist

After a run starts, inspect more than the top-level state:

run summary and selected row scope
row states and row counts
generated outputs
structured failures
events
usage and cost summaries
exports and download readiness
retry or follow-up lineage

Retry and lineage

Retry work creates a new run. It does not mutate terminal rows in the source run. The retry run should preserve lineage to the original run and should be scoped to the eligible failed, flagged, or retryable skipped rows.

Use retry when the same pinned job spec version can reasonably resolve unresolved rows. Use a revised job spec and a new run when the instructions, schema, model, or quality bar must change.

Common mistakes

Mistake	Better behavior
Starting duplicate work because a create request timed out.	Use idempotency and inspect the existing run.
Treating a sample as approval for a full run.	Ask for separate approval for broader scope or spend.
Hiding failed rows because the run mostly succeeded.	Surface failures with codes, row context, and recovery guidance.
Calling retry a rerun.	Say retry run and preserve lineage to the original `runId`.
Exporting before review.	Confirm that outputs are usable.