A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Google Sheets API is how an app or AI agent works with a Google spreadsheet: reading cell values, appending rows, updating a range, or changing formatting and structure. Access is granted through an OAuth 2.0 access token, and the scopes on that token set whether a call can only read or can also write, and whether it reaches every spreadsheet on the account or only the files the app created. Google ships new capabilities as dated additions rather than minting new version numbers.
How an app or AI agent connects to Google Sheets determines what it can reach. An agent calls the API with an OAuth 2.0 access token, and the scopes on that token set whether it can read or change a spreadsheet, and whether it reaches every spreadsheet on the account or only the files it created.
The REST API takes and returns JSON at https://sheets.googleapis.com/v4. A call authenticates with an OAuth 2.0 access token in the Authorization header, and a spreadsheet is addressed by its spreadsheetId, the string from its URL. Cell ranges are given in A1 notation, like Sheet1!A1:B2. There is no first-party Model Context Protocol server for Google Sheets.
An app sends a user through Google's OAuth 2.0 consent flow and receives an access token tied to that person, plus a refresh token to renew it. The scopes requested set what the token can do, and Google's verification review applies to sensitive and restricted scopes before an app can use them with outside users.
A service account is a non-human Google identity that authenticates with its own key and obtains an access token without a consent screen. It can reach a spreadsheet that is shared with its email address, or, in Google Workspace, use domain-wide delegation to act as users in the organization.
The Google Sheets API is split into areas an agent can act on: a whole spreadsheet, the cell values inside it, and the individual sheets within. Reading cell values is one method, while changing a spreadsheet's structure, formatting, or charts goes through a single batch-update method.
Methods for reading a whole spreadsheet and changing its structure, formatting, and charts.
Methods for reading and writing the cell values inside a spreadsheet.
Methods for operating on individual sheets within a spreadsheet.
Methods for reading hidden developer metadata attached to a spreadsheet, sheet, or range.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SpreadsheetsMethods for reading a whole spreadsheet and changing its structure, formatting, and charts.4 | ||||||
| GET | /v4/spreadsheets/{spreadsheetId} | Return a spreadsheet's properties, sheets, and optionally its cell data. | read | spreadsheets.readonly | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets.readonly. Also satisfied by spreadsheets, drive.readonly, drive.file, or drive. Use the includeGridData parameter to return cell values. Acts onspreadsheet Permission (capability) spreadsheets.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets | Create a new spreadsheet, optionally with sheets and data set in the request. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. Acts onspreadsheet Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}:batchUpdate | Apply one or more updates to a spreadsheet, like formatting cells, adding sheets, charts, or filters. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. This is the single method for all structural and formatting changes; requests apply atomically. Acts onspreadsheet Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}:getByDataFilter | Return a spreadsheet selected by data filters rather than by A1 ranges. | read | spreadsheets.readonly | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets.readonly. Also satisfied by spreadsheets, drive.readonly, drive.file, or drive. A read despite using POST. Acts onspreadsheet Permission (capability) spreadsheets.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Cell valuesMethods for reading and writing the cell values inside a spreadsheet.10 | ||||||
| GET | /v4/spreadsheets/{spreadsheetId}/values/{range} | Return cell values from a single range, given in A1 notation. | read | spreadsheets.readonly | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets.readonly. Also satisfied by spreadsheets, drive.readonly, drive.file, or drive. Acts onvalueRange Permission (capability) spreadsheets.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v4/spreadsheets/{spreadsheetId}/values/{range} | Write cell values to a single range, given in A1 notation. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. Overwrites the target range in place. Acts onvalueRange Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}/values/{range}:append | Append rows of values after the last row of data in a range, like adding records to a table. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. Finds the existing table and writes below it. Acts onvalueRange Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}/values/{range}:clear | Clear the values from a range, leaving formatting and other properties in place. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. Removes only values, not cell formatting. Acts onvalueRange Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v4/spreadsheets/{spreadsheetId}/values:batchGet | Return cell values from multiple ranges in one request. | read | spreadsheets.readonly | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets.readonly. Also satisfied by spreadsheets, drive.readonly, drive.file, or drive. Acts onvalueRange Permission (capability) spreadsheets.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}/values:batchUpdate | Write cell values to multiple ranges in one request. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. Acts onvalueRange Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}/values:batchGetByDataFilter | Return cell values from ranges selected by data filters rather than A1 ranges. | read | spreadsheets.readonly | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets.readonly. Also satisfied by spreadsheets, drive.readonly, drive.file, or drive. A read despite using POST. Acts onvalueRange Permission (capability) spreadsheets.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}/values:batchClear | Clear the values from multiple ranges in one request, leaving formatting in place. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. Acts onvalueRange Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}/values:batchUpdateByDataFilter | Write cell values to ranges selected by data filters rather than A1 ranges. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. Acts onvalueRange Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}/values:batchClearByDataFilter | Clear the values from ranges selected by data filters rather than A1 ranges. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. Acts onvalueRange Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sheets (tabs)Methods for operating on individual sheets within a spreadsheet.1 | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}/sheets/{sheetId}:copyTo | Copy a single sheet from one spreadsheet into another spreadsheet. | write | spreadsheets | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets. Also satisfied by drive.file or drive. Writes into the destination spreadsheet, so the token needs access to both files. Acts onsheet Permission (capability) spreadsheetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Developer metadataMethods for reading hidden developer metadata attached to a spreadsheet, sheet, or range.2 | ||||||
| GET | /v4/spreadsheets/{spreadsheetId}/developerMetadata/{metadataId} | Return a single piece of developer metadata by its ID. | read | spreadsheets.readonly | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets.readonly. Also satisfied by spreadsheets, drive.readonly, drive.file, or drive. Acts ondeveloperMetadata Permission (capability) spreadsheets.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/spreadsheets/{spreadsheetId}/developerMetadata:search | Search a spreadsheet's developer metadata by a data filter. | read | spreadsheets.readonly | Current | |
Full scope: https://www.googleapis.com/auth/spreadsheets.readonly. Also satisfied by spreadsheets, drive.readonly, drive.file, or drive. A read despite using POST. Acts ondeveloperMetadata Permission (capability) spreadsheets.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| Event | What it signals | Triggered by |
|---|
Google Sheets limits how fast an app can call by a per-minute request quota, counted separately for reads and writes, and at both the project level and the per-user level.
Google Sheets meters calls by a per-minute request quota, not by a per-method cost, so individual methods carry no point weighting. Reads and writes are counted separately, and each is capped at 300 requests per minute per project and 60 requests per minute per user per project. The quota refreshes every minute. Going over returns HTTP 429 with a RESOURCE_EXHAUSTED error, and the documented response is to slow down and retry with truncated exponential backoff. There is no charge for usage within these limits.
The Sheets API does not paginate value reads; a get or batchGet returns the full requested range in one response. A request to read or write very large ranges is bounded by the request size and the per-request processing time limit rather than by page cursors.
There is no hard size limit on a single request, but a payload of roughly 2 MB or less is recommended for speed, and any single request that runs longer than 180 seconds returns a timeout. A spreadsheet itself is bounded by Google Sheets product limits, like the cell count cap, which the API shares.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | The request was malformed, for example a bad A1 range, an unparseable field, or an invalid parameter value. | Check the request against the reference for the method, fix the range or parameters, and resend. The request is not retryable as-is. |
| 401 | UNAUTHENTICATED | No valid OAuth credentials were supplied, or the access token has expired. | Refresh the access token using the refresh token, or send the user back through consent, then retry. |
| 403 | PERMISSION_DENIED | The token lacks a scope the method needs, or the authenticated identity does not have access to the spreadsheet. | Request the right scope, like spreadsheets for writes, or share the spreadsheet with the account, then retry. |
| 404 | NOT_FOUND | The spreadsheet ID does not exist, or it is not visible to the authenticated identity. | Verify the spreadsheetId and confirm the identity has access to the file. |
| 429 | RESOURCE_EXHAUSTED | A per-minute quota was exceeded, for reads or writes, at the project or per-user level. | Slow the request rate and retry with truncated exponential backoff. Batch related calls to use fewer requests. |
| 500 | INTERNAL | An unexpected error on Google's side while processing the request. | Retry with backoff, and file a report on the Sheets API issue tracker if it persists. |
| 503 | UNAVAILABLE | The service is temporarily unavailable, or the spreadsheet is too complex for the request to complete in time. | Retry with backoff, keep to roughly one request per second per spreadsheet, batch operations, and request only the data needed. |
Google Sheets uses one URL version of its API, v4, and ships dated feature updates through its release notes rather than minting new version numbers.
Google Sheets exposes one URL version of its API, v4, and adds capabilities through dated release-note entries rather than new version numbers. Recent additions include smart chips and table operations.
Smart chips that reference Drive files and people became generally available in the Sheets API, so an app can create, update, and read them.
The Sheets API gained the ability to create and modify tables and take basic actions on them.
The legacy v3 API was turned down, leaving v4 as the supported version, with migration guidance provided.
Google introduced the v4 API, a JSON REST interface for reading and modifying spreadsheets, replacing the older v3 design.
v4 is the current and only supported version; the older v3 was turned down in 2021.
Google Sheets API release notes ↗Bollard AI sits between a team's AI agents and Google Sheets. Grant each agent exactly the access it needs, read or write, and every call is checked and logged.