---
title: "Read a bounded row sample of a named relation for the Explorer's preview UI."
method: POST
path: "/v1/data/preview"
tags: ["data"]
---

# Read a bounded row sample of a named relation for the Explorer's preview UI.

`POST /v1/data/preview`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/data/preview`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Reads up to `maxRows` rows (clamped server-side to [1, 1000], defaulting to 1000) of one
NAMED relation `[database.]schema.table` — never arbitrary caller SQL — for the
Explorer's row-sample UI (DVT-1807/1809). Same typed-parts identifier validation as
`POST /v1/data/describe`.

MUST resolve identity, the caller's-rights token, and the per-dashboard query role
role-pin byte-for-byte the same way `POST /v1/data/query` does — a preview never
diverges in privilege from a query on the same source. Same tenant gate and
render-session source scoping as the query/describe/objects paths: a cross-tenant
`sourceId` returns 404.

Never served from or written to the `POST /v1/data/objects` listing cache — every
preview is a live warehouse read under the caller's own resolved identity.

## Request body

- PreviewRequest
  - `sourceId` string, required: Connection name or UUID (resolved per connection-as-code.md).
  - `database` string: Relation database part. Optional for Postgres (the connection is bound to one database); used to fully qualify a Snowflake relation. Identifier allowlist: letters, digits, _ or $, up to 255 chars.
  - `schema` string, required: Relation schema part. Identifier allowlist: letters, digits, _ or $, up to 255 chars.
  - `table` string, required: Relation table part. Identifier allowlist: letters, digits, _ or $, up to 255 chars.
  - `maxRows` integer: Requested row cap. Clamped server-side to [1, 1000]; omit to default to 1000 ("first 1,000 rows").

## Response `200`

A bounded row sample of the relation.

- PreviewResponseEnvelope
  - `data` object, required
    - `rows` object[]
    - `columns` string[]
    - `rowCount` integer
    - `truncated` boolean: True when the sample was cut off at maxRows (or the engine's 1000-row preview ceiling) — the rows are a prefix of the relation, not all of it.
  - `meta` Meta, required: Response metadata.
    - `requestId` string, required: Correlates with the X-Request-Id header.
    - `total` integer: Item count, present on collection responses.
    - `nextCursor` string, nullable: Opaque keyset-pagination cursor, present on paginated responses (e.g. GET /v1/dashboards) when more rows exist beyond this page. Pass it back as the `cursor` query param to fetch the next page; absent or null on the last page.
    - `roleResolveDegraded` boolean: Snowflake mode only (DVT-2260), on GET /v1/dashboards: present and true when the caller's live Snowflake role resolution failed or was unavailable — role-shared dashboards may be missing from this page. Omitted (not merely false) whenever resolution succeeded or the role-share arm does not apply (off snowflake mode, an org admin/owner, or off the ingress listener).

## Other responses

- `400`: The preview was rejected before or during execution. Three shapes, distinguished by the Problem `type`: - `https://docs.dvt.dev/errors/bad-query` (the default) — the requested relation could not be read (e.g. a statement timeout). - `https://docs.dvt.dev/errors/no-warehouse` (DVT-2297) — a caller's-rights (Snowflake `spcs_token`) session has no resolvable warehouse: no default warehouse set for the caller's Snowflake user, and no `consumer_warehouse` reference bound the caller's role can use. The `suggestion` field tells the caller which admin action fixes it; retrying without a warehouse configured will fail identically. - `https://docs.dvt.dev/errors/caller-session-unconfirmed` (DVT-3780, DVT-4299, DVT-4318) — the caller's-rights session's safety parameters could not be confirmed in band, neither as requested on the login nor after the engine re-pinned them with `ALTER SESSION SET` and read them back again. If that re-pin is itself refused but `MULTI_STATEMENT_COUNT` still reads back as 1, the engine accepts the session in client-bound mode instead, enforcing the statement timeout client-side on every statement — the bound is enforced by dvt cancelling the statement from its own process; a statement detached by an engine restart falls back to the account-level `STATEMENT_TIMEOUT_IN_SECONDS`. This error remains for a parameter read that fails outright, a single-statement count that does not confirm, a re-pin that "succeeds" but still disagrees on read-back, or a non-positive configured timeout. Not a grant, SQL, or warehouse problem and not remediable by the consumer: report it to dvt support.
- `401`: Missing, invalid, or expired session.
- `403`: The caller's role does not permit this action.
- `404`: Resource does not exist.
- `409`: Two shapes, distinguished by the Problem `type`: - `https://docs.dvt.dev/errors/oauth-consent-required` — the source is a per-user OAuth (`oauth_passthrough`) connection and the caller has not connected their warehouse account yet, or their stored grant has expired/been revoked (DVT-123). The client starts the consent flow at `GET /v1/connections/{connectionId}/oauth/authorize` and retries. - `https://docs.dvt.dev/errors/not-queryable-connection` (DVT-2540) — the resolved connection is configured for writeback only (`kind='writeback'`) and cannot be used as a query source. No self-heal retry; bind a pushdown connection to this `sourceId` instead. Both shapes carry a `connectionId` extension (the consent target, or the non-queryable connection).
- `429`: Two causes, distinguished by the Problem `type` (DVT-3464 split this from a single shared `errors/rate-limited`, which made an engine-capacity shed indistinguishable from an actual rate limit): - `https://docs.dvt.dev/errors/rate-limited` — a rate or concurrency limiter for this operation rejected the request before it reached the engine. See `components/responses/RateLimited` for the general per-actor SEC-2 tier; some operations stack an additional operation-specific limiter (the query submit rate limit, the per-org running-job cap, or the trial query ceiling). - `https://docs.dvt.dev/errors/engine-at-capacity` — the engine's own admission control (ADR-0053) shed the request before it reached the warehouse — a dvt engine limit, not a warehouse or rate problem (DVT-765). `suggestion` names the actual wait in seconds and, when the engine reports a scope, whether the per-org or global engine concurrency cap was hit. Both carry `Retry-After` (seconds); back off for at least that long before retrying.
- `502`: The analytics engine could not be reached (`https://docs.dvt.dev/errors/engine-unavailable`) or returned an error (`https://docs.dvt.dev/errors/engine-error`). One 502 on this shape is NOT an engine fault and says so: when Snowflake refuses the caller's-rights LOGIN, the Problem type is `https://docs.dvt.dev/errors/caller-connect-refused` — no session was established and the caller's SQL was never reached, so the remediation is a fresh dvt session rather than the engine logs (DVT-4345).

---

[API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)