---
title: "Cheap change-detection and flush-state poll for a Sheet."
method: GET
path: "/v1/sheets/{id}/status"
tags: ["sheets"]
---

# Cheap change-detection and flush-state poll for a Sheet.

`GET /v1/sheets/{id}/status`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/sheets/{id}/status`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Neon-only (never touches the engine or the warehouse) status endpoint the sheet
panel polls (DVT-5181, ADR-0091 D4). Requires `sheet:read`.

`changeToken` is an opaque, server-keyed hash of the sheet's version, WAL
sequence position and flush watermark (and, for a linked sheet whose base
relation is itself a dvt sheet, the base sheet's too). Compare it for equality
only: a different value means "something changed, re-query". It carries no
other meaning and is stable across API replicas.

`flushState` precedence: `synced` when nothing is pending; otherwise the last
flush attempt's `blocked` / `stranded` outcome; otherwise `syncing`.

Not available to render sessions.

## Response `200`

The sheet's current change token and flush state.

- object
  - `data` SheetStatus, required: Result of GET /v1/sheets/{id}/status (DVT-5181).
    - `changeToken` string, required: Opaque change-detection token. Compare for equality only.
    - `pendingCount` integer, required: Number of WAL entries not yet flushed to the warehouse.
    - `flushedThroughSeq` integer, required: Highest WAL sequence number below the oldest unflushed entry.
    - `lastFlushedAt` string, date-time, nullable, required: When the last successful flush committed; null if never.
    - `flushState` 'synced' | 'syncing' | 'blocked' | 'stranded', required: "synced" — nothing pending. "syncing" — edits are saved and awaiting flush. "blocked" — the last flush attempt hit a precondition an admin must resolve (see `flushCause`). "stranded" — the sheet's warehouse target collides with another sheet's; rename the sheet or its folder.
    - `flushCause` string: Cause code for a `blocked` state; omitted otherwise.
  - `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

- `401`: Missing, invalid, or expired session.
- `403`: The caller's role does not permit this action.
- `404`: Resource does not exist.
- `503`: Sheet status is not configured on this deployment.

---

[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)