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.

GET /organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/runs

List runs for a package

cURL

curl --request GET \
  --url https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/runs \
  --header 'Authorization: Bearer <token>'

200

[
  {
    "id": "<string>",
    "buildNumber": 123,
    "trigger": "PUBLISH",
    "status": "BUILDING",
    "targetSourceName": "<string>",
    "targetDimension": "<string>",
    "targetModelFilePath": "<string>",
    "targetIncludeUpstream": true,
    "triggeringVersionId": "<string>",
    "buildPlan": {
      "sourceCount": 123,
      "builtSources": [
        "<string>"
      ],
      "reusedSources": [
        "<string>"
      ],
      "unsupportedSources": [
        "<string>"
      ],
      "failedSources": {},
      "dimensionCount": 123,
      "builtDimensions": [
        "<string>"
      ],
      "failedDimensions": {},
      "nodes": [
        {
          "key": "<string>",
          "id": "<string>",
          "nodeType": "SOURCE",
          "sourceName": "<string>",
          "status": "PENDING",
          "materialized": true,
          "tableName": "<string>",
          "modelFilePath": "<string>",
          "dimension": "<string>",
          "rowCount": 123,
          "lastIndexedAt": "2023-11-07T05:31:56Z",
          "error": "<string>",
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z"
        }
      ],
      "edges": [
        {
          "from": "<string>",
          "to": "<string>"
        }
      ]
    },
    "startedAt": "2023-11-07T05:31:56Z",
    "completedAt": "2023-11-07T05:31:56Z",
    "error": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
]

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_ -]+$

Query Parameters

versionId · string

Only return runs that impacted this version (derived filter). Version identifier pattern supporting dots and dashes

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

sourceName · string

Only return runs targeting this source.

dimension · string

Only return runs targeting this dimension.

limit · integer · default: -1

Maximum number of items to return. Use -1 or omit to return all results. Valid values: -1 (all results) or 1–500.

Required range: -1 <= x <= 500

offset · integer · default: 0

Number of items to skip before starting to return results

Required range: x >= 0

Response

200

application/json

List of runs retrieved successfully

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.

Show child attributes

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>