Skip to main content
GET
Get an index

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_.-]+$
indexId
string
required

The unique identifier of the index (binding)

Response

Index retrieved successfully

A version's serving anchor for one indexed (#(index)-tagged) dimension. It binds the version to the content-addressed, package-scoped built index (shared across versions, and — when the source is materialized — derived from the materialized table). That underlying artifact and its content address are internal and never exposed here.

id
string
sourceName
string

Fully-qualified source name within the package that owns the dimension.

dimension
string

The indexed dimension path (e.g. "country" or "people.name").

modelFilePath
string

The model file that declares this (source, dimension). Two files in one package version can declare the same source + dimension name with different definitions (each its own index), so this disambiguates otherwise-identical entries. Empty for legacy/unknown.

status
enum<string>
Available options:
PENDING,
READY,
FAILED
error
string

When status is FAILED, the reason the most recent build for this dimension failed — a read-time projection of the failing built index's error, surfaced inline so the cause is visible without drilling into individual runs. Null while PENDING/READY.

stale
boolean
read-only

True when this index is serving non-current data for any reason (docs/persistence.md §9.7). Unifies the reused-over-failed-source case (SOURCE_BUILD_FAILED) with age-based staleness against a declared index freshness.window (FRESHNESS_WINDOW_EXCEEDED, §9.5). The machine-readable cause(s) are in staleReasons. Display-only: the index still serves its prior values. False/absent otherwise.

staleSince
string<date-time> | null
read-only

The fresh→stale crossover instant — the age-based component (lastIndexedAt + effective freshness.window). Null when the staleness is only failure-derived, or when the index 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
rowCount
integer<int64>

Number of indexed values currently serving for this dimension (null until first READY build).

lastIndexedAt
string<date-time>

When the currently serving index generation was built (null until the first READY build).

scope
enum<string>

The scope mode this index was built under (replaces the removed per-dimension sharing): version = version-owned; package = reusable across the package's own versions when fresh. Null = unknown. The dimension-grain analog of Materialization.scope, and — like it — a per-anchor convenience mirror of the canonical Version.scope (declared once at the package-manifest root, uniform across the version), not an independent per-dimension knob.

NOTE (current phase): unlike Materialization.scope, this value is display metadata only — it does NOT isolate the index artifact. Index artifacts remain content-addressed by index_entity_id and are reused across versions regardless of scope (identical definition + data identity ⇒ identical index, so reuse is result-correct). A version-scoped index therefore records its owning version but may still share one physical artifact with another version that binds the same address; per-version artifact isolation lands with the index-cadence scheduler (persistence.md §9.5).

Available options:
version,
package
refresh
string

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

freshnessWindowSeconds
integer<int64>

The dimension's declared #(index ... freshness.window=...) refresh objective, in seconds (parsed from the "24h"/"7d" surface form). Null = unset — index freshness is opt-in per dimension (§9.5), so a bare #(index) reports nothing and no proactive cadence applies.

freshnessFallback
enum<string>

The dimension's declared #(index ... freshness.fallback=...) — query-time behavior intent when the window is missed (indexes have no gate today; metadata). Null = unset.

Available options:
live,
stale_ok,
fail
createdAt
string<date-time>
updatedAt
string<date-time>