List runs for a package
Lists build/refresh runs for this package, most recent first. A run is a single package-level build event carrying typed units — materialized sources (table units) and built indexes (index units). 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). Runs are version-independent: their artifacts may be shared across versions.
Optional filters narrow the list:
versionId— only runs that impacted the given version (i.e. whose triggering publish was that version, or that built/refreshed a unit the version binds). This is a derived view, not a stored scope; a refresh with no triggering publish can still impact a version, and one run can impact many.sourceName/dimension— only runs targeting that source/dimension.
Authorization: Requires read access to the package.
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_ -]+$Query Parameters
Only return runs that impacted this version (derived filter). Version identifier pattern supporting dots and dashes
^[a-zA-Z0-9_.-]+$Only return runs targeting this source.
Only return runs targeting this dimension.
Maximum number of items to return. Use -1 or omit to return all results. Valid values: -1 (all results) or 1–500.
-1 <= x <= 500Number of items to skip before starting to return results
x >= 0Response
List of runs retrieved successfully
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.