crate.surface(name, params)

surface(name: SurfaceName, params: SurfaceParams, opts?: RequestOptions): Promise<SurfaceRowsResponse>

The generic cluster-keyed surface read — one operation serves every row registered in surfaces. name is the schema-qualified registry key (pass it verbatim from a surfaces() row’s name); cluster is the 64-hex identity key in THAT surface’s registered keyspace — most surfaces are artist-grain, but seen.song_station_journey is keyed on a recording-grain cluster, not the artist (check the row’s key.keyspace before calling). A key from the wrong keyspace fails soft as an empty honest_gap, never an error. state is one of present (rows), honest_gap (0 rows — a normal answer, not an error), or degraded (still HTTP 200, rows: [] — the dedicated surface-reader pool/role hasn’t landed on the replica yet; branch on it, don’t retry expecting rows). cluster-row grain surfaces (cap 1/1) ignore after/limit and answer with 0-1 rows; cluster-multirow/cluster-edge-list grains keyset-paginate via the opaque after cursor from a prior page’s next_after — pass it back verbatim, never construct or decode it. Cursor durability: cursors are page-iteration handles, not durable bookmarks — some surfaces build them from producer-internal columns that can change across producer re-crawls, so a stored cursor may silently skip or repeat rows later. Restart from the first page (omit after) for a fresh read rather than resuming a cursor saved from a previous session.

Endpoint	GET /api/v2/surface/{name}
Auth	key
Returns	SurfaceRowsResponse
Retryable	yes
Idempotent	yes

Example

const page = await crate.surface('seen.radio_play_v1', { cluster: clusterId, limit: 50 });
if (page.state === 'present') page.rows.forEach((r) => console.log(r.station_key));
const next = page.next_after
  ? await crate.surface('seen.radio_play_v1', { cluster: clusterId, after: page.next_after })
  : null;

Throws

• invalid_name — (400) for an unregistered/unknown name — the error carries every valid name + doc_url + next (call surfaces).