List materializations for a version

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

import requests

url = "https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "id": "<string>",
    "sourceName": "<string>",
    "modelFilePath": "<string>",
    "error": "<string>",
    "connectionName": "<string>",
    "servingRunId": "<string>",
    "servingBuildNumber": 123,
    "materializedTableName": "<string>",
    "servingStartedAt": "2023-11-07T05:31:56Z",
    "refresh": "<string>",
    "freshnessWindowSeconds": 123,
    "stale": true,
    "staleSince": "2023-11-07T05:31:56Z",
    "staleReasons": [],
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
]

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

materializations

List materializations for a version

Lists the per-source materializations bound to a package version (Malloy Persistence v0), most recent first. Each materialization is the lineage anchor for one persist source of the version — identified within the version by its (sourceName, modelFilePath) — and points at the physical table currently serving that source.

In v0 materializations are addressed under the version that binds them. Package-level (cross-version) materialization resources will be added once versions can share materialized tables.

Authorization: Requires read access to the package.

GET

organizations

{organizationName}

environments

{environmentName}

packages

{packageName}

versions

{versionId}

materializations

List materializations for a version

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

import requests

url = "https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{organization}.admin.credibledata.com/api/v0/organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "id": "<string>",
    "sourceName": "<string>",
    "modelFilePath": "<string>",
    "error": "<string>",
    "connectionName": "<string>",
    "servingRunId": "<string>",
    "servingBuildNumber": 123,
    "materializedTableName": "<string>",
    "servingStartedAt": "2023-11-07T05:31:56Z",
    "refresh": "<string>",
    "freshnessWindowSeconds": 123,
    "stale": true,
    "staleSince": "2023-11-07T05:31:56Z",
    "staleReasons": [],
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
]

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

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

versionId

string

required

The unique identifier of the version Version identifier pattern supporting dots and dashes

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

Response

List of materializations retrieved successfully

string

sourceName

string

Fully-qualified persist source name within the package.

modelFilePath

string

The model file that declares this source. Two files in one version may declare the same sourceName as distinct anchors, so a scoped source rerun must pass both sourceName and modelFilePath to target the right one (mirrors Index.modelFilePath). Empty string (never null) for an anchor with no recorded path — the column is NOT NULL DEFAULT ''.

status

enum<string>

Available options:

PENDING,

READY,

FAILED

error

string

When status is FAILED, the reason the most recent build failed — the error of the materialization's latest run (where build failures occur), surfaced here so the cause (e.g. a BigQuery "Permission bigquery.tables.delete denied" warehouse error, or a build that produced no table) is visible inline without drilling into individual runs. A read-time projection of the run's error; null while PENDING/READY.

connectionName

string

Name of the connection whose warehouse holds the currently serving materialized table (null until first READY build).

servingRunId

string

Id of the run whose materialized table this version currently serves; the physical table name is exposed directly on this DTO as materializedTableName (and per-source on that run's buildPlan.nodes[].tableName). Auto-advances to the latest successful run. A materialization always has a serving run once it has a successful build; null only until the first table is built.

servingBuildNumber

integer

The buildNumber (the "gNNN" the UI shows) of the run named by servingRunId, resolved server-side so the client can render the serving build label without a second, version-scoped run lookup. Under table reuse the serving run can belong to a prior version, so a client-side lookup against the current version's runs would miss it; this field is version-agnostic. Null until the first table is built, or for a legacy serving run created before build numbers existed.

materializedTableName

string

Physical name of the currently serving materialized table (null until the first READY build).

servingStartedAt

string<date-time>

When the currently serving table was materialized, i.e. began serving (null until the first READY build).

scope

enum<string>

The materialization scope mode this source's table was built under (replaces the removed per-source sharing): version = version-owned, no cross-version reuse; package = reusable across the package's own versions when fresh. Null = unknown (materialized before scope was recorded).

This is a per-anchor convenience mirror of the canonical Version.scope, not an independent per-source knob: scope is declared once at the package-manifest root and is uniform across every source and index of a version, so this always equals the owning version's scope. It is surfaced here so a single materialization is self-describing without a second getVersion; read Version.scope when you want the authoritative version-grain value.

Available options:

version,

package

refresh

string

The source's declared #@ persist ... refresh=... value ("full" | "incremental"), reported verbatim. Null = unset. Policy metadata for display (inert to the build today).

freshnessWindowSeconds

integer<int64>

The source's EFFECTIVE freshness window (after most-specific-wins resolution: source > model-file > package), in seconds — the control plane's refresh objective for this source's materialized table. Null = unset at every level (the platform default applies).

freshnessFallback

enum<string>

The source's EFFECTIVE freshness fallback — the declared query-time behavior when the window is missed. Null = unset.

Available options:

live,

stale_ok,

fail

stale

boolean

read-only

True when this source is serving non-current data for any reason (docs/persistence.md §9.7). The unified staleness indicator; the machine-readable cause(s) are in staleReasons. False/absent otherwise.

staleSince

string<date-time> | null

read-only

The fresh→stale crossover instant — the age-based component (dataAsOf + freshness.window). Null when the staleness is only failure-derived (no age crossover), or when the source is fresh.

staleReasons

enum<string>[]

read-only

The machine-readable staleness cause(s) (§9.7). Empty when fresh.

Machine-readable cause for an artifact's staleness (docs/persistence.md §9.7 — one indicator, orthogonal reasons). Split into GATING reasons (their presence sets stale=true) and ANNOTATION reasons (they explain why an already-stale artifact keeps aging, never flip it on their own):

FRESHNESS_WINDOW_EXCEEDED (gating) — data age passed the declared freshness.window (§9.3 tables, §9.5 indexes).
SOURCE_BUILD_FAILED (gating) — serving prior values because this version's source materialization FAILED (the reused-over-failed case, generalized; symmetric for a source whose latest rebuild failed while a prior generation still serves).
REFRESH_IN_PROGRESS (annotation) — a scheduled refresh has fired but no fresher generation has landed yet (self-heals).
LAST_REFRESH_FAILED (annotation) — the refresh stream was disarmed after repeated fires without landing a fresher generation.
WINDOW_BELOW_BUILD_TIME (annotation) — the declared freshness window is shorter than the estimated build duration, so the objective is physically unachievable (the rebuild cannot complete inside the window). The window needs widening, or what it covers reducing.

Available options:

FRESHNESS_WINDOW_EXCEEDED,

SOURCE_BUILD_FAILED,

REFRESH_IN_PROGRESS,

LAST_REFRESH_FAILED,

WINDOW_BELOW_BUILD_TIME

createdAt

string<date-time>

updatedAt

string<date-time>

Update database connection Get a materialization

Overview

organizations

organizationPermissions

packages

environments

environmentPermissions

packagePermissions

versions

connections

materializations

indexes

runs

workspaces

workspacePermissions

documents

documentPermissions

groups

bookmarks

attributes

users

demo

invites

permissions

List materializations for a version

Authorizations

Path Parameters

Response