Get the current state
Returns the workbook's state hash, for polling and for use as a precondition on a structural change.
Permission
The key must be granted sheets.values.read
A key without it gets 403 insufficient_scope, with the missing permission named in details.
Two uses, one value. Poll it to notice somebody else's change — there are no webhooks for spreadsheets — and send it as If-Match on a structural write so a change that moves data cannot land on a stale view.
Path parameters
| Field | Type | Description |
|---|---|---|
id required |
string | The spreadsheet to check. |
Request
curl https://api.veruapis.com/v1/spreadsheets/:id/state \
-H "Authorization: Bearer vak_live_..."Response
| Field | Type | Description |
|---|---|---|
document_id |
string | |
state |
string | An opaque token that changes whenever the document does. Compare it with your last one; do not parse it. |
checked_at |
RFC 3339 | When the answer was computed. |
{
"data": {
"document_id": "0199a1c2-6f3e-7a41-b8d2-5e9f0c3a7b41",
"state": "a1b2c3d4e5f6a7b8",
"checked_at": "2026-09-09T12:00:00Z"
},
"meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}Two uses, and they are the same value: poll it to notice someone else's change, and send it as If-Match on a structural write. There are no webhooks for spreadsheets, so polling this is how you watch a document.
Every failure uses the same shape, with a stable string code you can branch on. See the error reference.
Related
- POST Append rows
- POST Read several ranges
- POST Change a spreadsheet's structure
- POST Write several ranges
- POST Clear a range
- GET List the sheets in a spreadsheet
- GET Read a range
- PUT Write a range