Concepts · Runs

Runs

Runs are executions of workflow templates. They are the canonical experimental record: what happened, when it happened, how long each step took, what it cost, and whether the output was worth keeping.

Lifecycle

status transitionsascii

queued ─▶ running ─▶ review ─▶ completed
                       │
                       └─▶ failed

Status values

Status	Meaning
`queued`	Accepted by the API, waiting for execution.
`running`	Actively executing one or more steps.
`review`	Produced an artifact awaiting operator review.
`completed`	Final state. Artifact accepted, or no review required.
`failed`	Terminal error. error_code records the cause.

Timing fields

Field	Meaning
`queuedAt`	Wall time the run was accepted by the API.
`startedAt`	Wall time execution began on a worker.
`firstArtifactAt`	Wall time the first usable artifact existed.
`completedAt`	Wall time the run reached a terminal state.
`durationMs`	startedAt to terminal state, in milliseconds.
`queueWaitMs`	queuedAt to startedAt, in milliseconds.
`timeToFirstArtifactMs`	startedAt to first persisted artifact, in milliseconds.
`timeToFinalArtifactMs`	startedAt to final processed artifact, in milliseconds.

Example run

GET /v1/runs/run-a1b2c3d4json

{
  "id": "run-a1b2c3d4",
  "templateId": "generate-clip-art-asset",
  "status": "completed",
  "queuedAt":        "2026-05-16T22:14:12.482Z",
  "startedAt":       "2026-05-16T22:14:12.604Z",
  "firstArtifactAt": "2026-05-16T22:14:43.711Z",
  "completedAt":     "2026-05-16T22:14:54.681Z",
  "durationMs":          42077,
  "queueWaitMs":           122,
  "timeToFirstArtifactMs": 31107,
  "timeToFinalArtifactMs": 42077
}

Step telemetry

Each run carries a runSteps array. The step catalog varies by workflow, but every run opens with prompt resolution and closes with artifact creation. Steps are named with a dotted convention so they stay groupable across templates.

Lifecycle steps

Present on every run, regardless of workflow.

Step	Records
`prompt.resolve`	Resolved style descriptors and content-type template into the final prompt.
`storage.upload`	Persisted the output file(s) to storage.
`artifact.create`	Final persistence of the artifact record and its link to the run.

Workflow-specific steps

Example: the generate-clip-art-asset workflow adds these steps between prompt resolution and artifact creation.

Step	Records
`image.generate`	Provider call that produced the raw image.
`background.remove`	Background-removal model invocation.
`image.convert_webp.*`	PNG to WebP conversion for raw and processed outputs.