Read and edit Sheets with agents

Use stable IDs, bounded reads and conditional mutations for safe shared Sheet work.

These steps apply to the public API, connected MCP clients and the in-app assistant. Read current descriptors before execution; examples use illustrative IDs and versions.

Discover structure, then read data

Find the Sheet through sheets.list or workspace.search.
Read sheets.get for column IDs, types, select-option IDs and metadata versions.
Query only the relevant rows and columns with sheets.query. Use sheets.aggregate for counts and aggregates instead of downloading the full Sheet.
Follow opaque nextCursor values and use the returned snapshotRevision as expectedRevision on subsequent pages. Keep the query consistent while paging.

First page input

json

{  "sheetId": "11111111-1111-4111-8111-111111111111",  "columnIds": null,  "expectedRevision": null,  "query": {    "cursor": null,    "direction": "forward",    "filters": [],    "focusRowId": null,    "history": false,    "pageSize": 100,    "q": null,    "sort": [],    "version": null  }}

The response separates page.rows and sparse page.cells. Cells contain rowId, columnId, rawValue, projectedValue and entityVersion; row position is not identity. A cell may also include enrichment presence. Re-query relevant Sheet rows for current enrichment progress; inspect proposals with sheets.get_enrichment_proposals when needed.

Make conditional changes

Use sheets.update_cells for typed cell patches. Supply the fresh entityVersion as expectedVersion; use "0" only for an absent cell. Select values use option IDs. Structural edits use the Sheet, column, view or order version required by their schema.

Cell update input

json

{  "sheetId": "11111111-1111-4111-8111-111111111111",  "idempotencyKey": "review-cell-example-001",  "patches": [    {      "rowId": "22222222-2222-4222-8222-222222222222",      "columnId": "33333333-3333-4333-8333-333333333333",      "expectedVersion": "12",      "rawValue": "Reviewed"    }  ]}

This example assumes a text column and version 12. Replace all IDs and the version with current reads. One update accepts at most 500 patches. A successful batch is atomic; separate batches can commit independently. On a conflict, read and reconcile current data, then issue the newly intended edit with a new key. Do not remove the version check to force an old value over a collaborator's edit.

Keep the returned operation ID, revision and changeset ID when provided. Exact recovery uses the same key and payload; different work requires a different key. Undo is conditional too: inspect its outcome rather than assuming later edits were reversed.

Choose the operation by task

Task	Operation family
Create, rename, move, duplicate or archive Sheets	`sheets.create`, `sheets.rename`, `sheets.move_to_folder`, `sheets.duplicate`, `sheets.archive`
Insert records, move rows, update cells or remove rows	`sheets.insert_records`, `sheets.move_rows`, `sheets.update_cells`, `sheets.delete_rows`
Configure columns, select options or conversions	Discover the `sheets` column operations and their current descriptors.
Manage shared views	`sheets.create_view`, `sheets.update_view`, `sheets.reorder_views`, `sheets.delete_view`
Research cells and review proposals	`sheets.start_enrichment`, `sheets.cancel_enrichment`, `sheets.get_enrichment_proposals`, `sheets.review_enrichment_proposals`
Inspect or restore history, manage access	Discover the history, version and sharing operations permitted by your role.

Creating a saved view does not switch the person's current tab. Hidden columns are presentation state and remain accessible; hiding is not a permissions control.

Files and large analysis

sheets.export_csv returns a revision-consistent, bounded CSV snapshot. Set its maxBytes and inspect the result; this operation is capped at 1 MiB. Editing the downloaded CSV does not update the live Sheet. Apply selected changes through canonical operations.

The hosted assistant additionally has execution-local, read-only Sheet analysis helpers. External MCP clients can analyze bounded query results or exports with their own tools. Neither path should replace the live Sheet with an unversioned file upload.

For paid work, keep run/request identities, inspect terminal outcomes and account for unresolved billing. Leadbase owns capacity and provider routing. See Enrichment, API recovery and the portable agent skill.