Write several ranges

Writes several A1 ranges in one call.

POST /v1/spreadsheets/:id/values/batch-update

Permission

The key must be granted sheets.values.write

A key without it gets 403 insufficient_scope, with the missing permission named in details.

Applied as one document write, so somebody with the sheet open sees one change rather than a flicker of several.

Path parameters

Field	Type	Description
`id` required	string	The spreadsheet to write to.

Request body

Field	Type	Description
`data` required	object[]	The ranges to write. At least one, and they may span different tabs. Its fields are below.

Each item in data

Field	Type	Description
`range` required	A1 range
`values` required	array[][]	Rows, each an array of cells. A cell is a string, a number or a boolean; a formula is a string beginning with =. An empty string DELETES a cell rather than storing a blank, because a stored blank would keep it inside the sheet's used extent and widen every unbounded range from then on.

Request

curl https://api.veruapis.com/v1/spreadsheets/:id/values/batch-update \
  -X POST \
  -H "Authorization: Bearer vak_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "data": [
    { "range": "Sheet1!A2:B2", "values": [["North", 1200]] },
    { "range": "Summary!B1",   "values": [["=SUM(Sheet1!B2:B9)"]] }
  ]
}'

Idempotency-Key is required on every write. Retrying with the same key returns the original response rather than repeating the operation, so a timeout is something you retry rather than something you investigate.

Response

Field	Type	Description
`updated_cells`	integer	Across every range in the call.
`state`	string	The document's state after the write. Send it as If-Match on a structural change, or compare it with your last one to notice somebody else's edit.
`changed`	boolean	False when the write stored nothing new — writing a cell the value it already holds. Not an error and not worth retrying: no new state was produced and no collaborator was notified.

{
  "data": { "updated_cells": 3, "state": "b2c3d4e5f6a7b8c9", "changed": true },
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}

Worth knowing

Applied as one document write, so a colleague with the sheet open sees one change rather than a flicker of several. changed is false when the write stored nothing new — writing a cell the value it already holds.

Errors

Every failure uses the same shape, with a stable string code you can branch on. See the error reference.

POST `/v1/spreadsheets/:id/values/batch-update`

Your API key Used once, never stored.

id

data