Skip to main content
POST
Create a run (rebuild a version, or a single scoped unit)

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

organizationName
string
required

The unique identifier of the organization Standard identifier pattern for resource names

Pattern: ^[a-zA-Z0-9_ -]+$
environmentName
string
required

The unique identifier of the environment Standard identifier pattern for resource names

Pattern: ^[a-zA-Z0-9_ -]+$
packageName
string
required

The unique identifier of the package Standard identifier pattern for resource names

Pattern: ^[a-zA-Z0-9_ -]+$

Body

application/json

Request a run for a version. By default (no scope selectors) this is a full run: re-materialize every persist source in the version and rebuild every indexed dimension it defines, in one run. The optional sourceName / dimension / modelFilePath selectors narrow the run to a single unit (Phase C per-unit dispatch); a null selector widens to the whole version, so the whole-version full run stays the default.

versionId
string
required

The version to (re)build. With no scope selectors the run re-materializes all of the version's persist sources and rebuilds all of the dimensions they define. A version that predates the content-addressed index model is discovered and migrated into it as part of the same run.

sourceName
string

Optional. Restrict the run to a single persist source's table (Phase C per-source dispatch). The named source is force-rebuilt (a fresh generation at the same content address); its persist upstreams are referenced from their existing materialized tables, not rebuilt (unless includeUpstream is set). Null widens to every persist source in the version.

includeUpstream
boolean
default:false

Optional. Only meaningful when the target resolves to a source (sourceName set — for a source rerun, or an index rerun that also names its source). When true, the run also force-rebuilds the target's transitive upstream persisted sources (its full derivation closure), so the whole lineage feeding the target is refreshed rather than referenced from existing tables:

  • source target: rebuild the source and every persisted source it derives from.
  • index target (dimension set): rebuild the source table the index reads from and its upstream closure, then re-index. When false (default): a source target rebuilds only that source (its upstreams reused); an index target reuses the source table and only re-indexes. Ignored for a full run or a dimension target that names no source.
dimension
string

Optional. Restrict the run to a single indexed dimension's index. Combined with sourceName it targets that dimension on that source; alone it targets the dimension across the sources that define it (disambiguated by modelFilePath when set). Null widens to every indexed dimension in scope.

modelFilePath
string

Optional. Disambiguates a dimension defined in more than one model file. Null widens to every model file defining the matched dimension.

Response

Run created (build started)

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.

id
string
buildNumber
integer

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.

trigger
enum<string>
Available options:
PUBLISH,
ON_DEMAND,
SCHEDULER
status
enum<string>

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).

Available options:
BUILDING,
READY,
FAILED,
CANCELLED
targetSourceName
string

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.

targetDimension
string

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.

targetModelFilePath
string

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.

targetIncludeUpstream
boolean

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.

triggeringVersionId
string

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.

buildPlan
object

A run's build plan across both unit families. Two layers:

  1. 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 listRuns and getRun).
  2. 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 on getRun only; null on listRuns to keep the list payload small (mirrors how Version.buildPlan is getVersion-only). This graph is the single source of truth for a run's units — the internal content address (entity_id) is never exposed.
startedAt
string<date-time>
completedAt
string<date-time>
error
string

Run-level failure reason (planning/orchestration failure); per-unit failures live on the produced units.

createdAt
string<date-time>
updatedAt
string<date-time>