Namespace metadata

Request

GET /v2/namespaces/products/metadata

{
  // Proxied from Turbopuffer verbatim
  "schema": { },
  "approx_row_count": 12500,
  "approx_logical_bytes": 48800000,
  "created_at": "2026-03-15T10:30:45Z",
  "updated_at": "2026-05-12T18:49:00Z",
  "last_write_at": "2026-05-12T18:48:30Z",
  "index": { "status": "up-to-date" },

  // Layer enhancement
  "layer": {
    "stable_as_of": 1715600400000,
    "is_stable": true
  }
}

The layer block

Field	Meaning
stable_as_of	Epoch-ms watermark from the most recent stable poll. Null on cold start before the watcher has observed a stable namespace.
is_stable	Whether the most recent poll observed index.status == "up-to-date". False on cold start, true once the watcher catches up.

is_stable is the current signal — it drives the per-query filter-skip decision on the query path. stable_as_of is the historical watermark — the cut a filtered query would apply.

For snapshot history derived from these freshness signals, see Snapshots.

List namespaces

GET /v2/namespaces is a Layer-only augmented listing. It pages the upstream namespace list and enriches each row with the same freshness and cache signals surfaced above. It is the surface the dashboard’s inventory view reads.

GET /v2/namespaces?prefix=prod&page_size=100

{
  "namespaces": [
    {
      "name": "products",
      "row_count": 12500,
      "size_bytes": 48800000,
      "stable_as_of_ms": 1715600400000,
      "is_stable": true,
      "cache_state": {"state": "warm", "warm_inflight": false},
      "last_write_ms": 1715600399000,
      "shadow": false,
      "labels": {}
    }
  ],
  "next_cursor": "..."
}

Query param	Purpose
prefix	Restrict to namespaces whose name starts with this string.
cursor	Pagination cursor from a prior next_cursor.
page_size	Page size; the upstream list page is capped at 1000.

A per-row metadata failure degrades to a row with metadata_error set rather than dropping the namespace, so the list stays complete even when a single namespace’s metadata call fails. Responses are served from a short-TTL cache (NAMESPACE_LIST_CACHE_TTL_MS, default 10000) so dashboard polling does not fan out a metadata call per namespace per refresh.