Get a run
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The unique identifier of the organization Standard identifier pattern for resource names
^[a-zA-Z0-9_ -]+$The unique identifier of the environment Standard identifier pattern for resource names
^[a-zA-Z0-9_ -]+$The unique identifier of the package Standard identifier pattern for resource names
^[a-zA-Z0-9_ -]+$The unique identifier of the run
Response
Run retrieved successfully
A package-level build/refresh event (version-independent) — the single,
unified run resource. It records the requested scope and correlates the
dispatch; its concrete units are the typed artifacts it produced —
materialized sources (source nodes) and built indexes (index nodes) —
surfaced in the run's build plan (buildPlan.nodes/edges, populated on
getRun). A run defaults to a full run spanning both families — a
publish, an on-demand rebuild, and a scheduled re-materialization all
refresh a version's tables and its indexes — but may also be scoped to a
single unit (Phase C per-unit dispatch). Each produced unit advances its
own serving pointer independently, so a partial failure leaves the run
READY while the failed unit carries its own error.
Stable, 1-based build ordinal within the package — the "Build gNNN" the UI shows (zero-padded for display). Monotonic per package, assigned at run creation. This is the run build number, NOT the per-source physical table generation (the g in a materialized table name), which counts per-source rebuilds and diverges under reuse. Null only for legacy runs created before the number existed.
PUBLISH, ON_DEMAND, SCHEDULER Run lifecycle status, rolled up from the units it produced.
Non-terminal: BUILDING. Terminal: READY, FAILED, CANCELLED. A run is
READY once every produced unit is terminal; individual unit failures
are carried per node in the run's build plan (buildPlan.nodes, on getRun).
BUILDING, READY, FAILED, CANCELLED Requested target source (Phase C per-unit dispatch). Null on a whole-version run (the createRun default); set when createRun scoped the run to a single source via the sourceName selector. A null component widens to the whole package.
Requested target dimension (Phase C per-unit dispatch). Null on a whole-version run; set when createRun scoped the run to a single indexed dimension via the dimension selector.
Requested target model file (Phase C per-unit dispatch). Null on a whole-version run; disambiguates a dimension defined in more than one model file when the modelFilePath selector is set.
The scoped rerun's upstream choice (Phase C). Only meaningful with
targetSourceName/targetDimension: when true, the rerun also
force-rebuilt the target's transitive upstream persisted closure
(rather than reusing those upstream tables); false / absent = the
target alone (a source references its upstreams, an index reuses its
source table). Always false on a whole-version run.
The version this run was started for — the version whose publish drove a PUBLISH run, the version an on-demand full run rebuilds, or the version a scheduled re-materialization refreshes. Provenance only: the run itself is package-scoped and may impact other versions that bind the same dimension. Null only for a future package-level scoped refresh with no single initiating version.
A run's build plan across both unit families. Two layers:
- A diagnostic summary (counters + name lists): how many persist
sources (table units) and indexed dimensions (index units) it planned,
and their outcomes. Always populated (on both
listRunsandgetRun). - A stateful dependency graph (
nodes+edges): one node per source (materialized table) and per indexed dimension, each carrying that unit's live state, wired source -> index. Populated ongetRunonly; null onlistRunsto keep the list payload small (mirrors howVersion.buildPlanisgetVersion-only). This graph is the single source of truth for a run's units — the internal content address (entity_id) is never exposed.
Run-level failure reason (planning/orchestration failure); per-unit failures live on the produced units.