Read several ranges
Reads several A1 ranges in one call, instead of a request per range.
Permission
The key must be granted sheets.values.read
A key without it gets 403 insufficient_scope, with the missing permission named in details.
A POST that changes nothing: the ranges travel in a body because A1 notation in a query string needs escaping a caller should not have to think about. The cell cap applies to the whole call rather than to each range.
Path parameters
| Field | Type | Description |
|---|---|---|
id required |
string | The spreadsheet to read. |
Query parameters
| Field | Type | Description |
|---|---|---|
value_render |
string |
Applies to every range in the call. With computed the workbook is evaluated once for the whole request, not once per range.
storedcomputed
Defaults to stored
|
Request body
| Field | Type | Description |
|---|---|---|
ranges required |
string[] | The A1 ranges to read. At least one. |
Request
curl https://api.veruapis.com/v1/spreadsheets/:id/values/batch-get \
-X POST \
-H "Authorization: Bearer vak_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"ranges": ["Sheet1!A1:B2", "Summary!A1"]
}'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 |
|---|---|---|
value_ranges |
object[] | One entry per requested range, in the order asked for. Its fields are below. |
Each item in value_ranges
| Field | Type | Description |
|---|---|---|
range |
A1 range | |
values |
array[][] |
{
"data": {
"value_ranges": [
{ "range": "Sheet1!A1:B2", "values": [["Region", "Revenue"], ["North", "1200"]] },
{ "range": "Summary!A1", "values": [["Q3"]] }
]
},
"meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}One call rather than one per range, and the cell cap applies to the whole request. A POST because A1 notation in a query string needs escaping a caller should not have to think about.
Every failure uses the same shape, with a stable string code you can branch on. See the error reference.
Related
- POST Append rows
- POST Change a spreadsheet's structure
- POST Write several ranges
- POST Clear a range
- GET List the sheets in a spreadsheet
- GET Get the current state
- GET Read a range
- PUT Write a range