Method: spreadsheets.batchUpdate

Applies one or more updates to the spreadsheet.

Each request is validated before being applied. If any request is not valid then the entire request will fail and nothing will be applied.

Some requests have replies to give you some information about how they are applied. The replies will mirror the requests. For example, if you applied 4 updates and the 3rd one had a reply, then the response will have 2 empty replies, the actual reply, and another empty reply, in that order.

Due to the collaborative nature of spreadsheets, it is not guaranteed that the spreadsheet will reflect exactly your changes after this completes, however it is guaranteed that the updates in the request will be applied together atomically. Your changes may be altered with respect to collaborator changes. If there are no collaborators, the spreadsheet should reflect your changes.

HTTP request

POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}:batchUpdate

The URL uses Google API HTTP annotation syntax.

Path parameters

Parameters
spreadsheetId

string

The spreadsheet to apply the updates to.

Request body

The request body contains data with the following structure:

JSON representation
{
  "requests": [
    {
      object(Request)
    }
  ],
  "includeSpreadsheetInResponse": boolean,
  "responseRanges": [
    string
  ],
  "responseIncludeGridData": boolean,
}
Fields
requests[]

object(Request)

A list of updates to apply to the spreadsheet. Requests will be applied in the order they are specified. If any request is not valid, no requests will be applied.

includeSpreadsheetInResponse

boolean

Determines if the update response should include the spreadsheet resource.

responseRanges[]

string

Limits the ranges included in the response spreadsheet. Meaningful only if [include_spreadsheet_response][] is 'true'.

responseIncludeGridData

boolean

True if grid data should be returned. Meaningful only if if [include_spreadsheet_response][] is 'true'. This parameter is ignored if a field mask was set in the request.

Response body

If successful, the response body contains data with the following structure:

The reply for batch updating a spreadsheet.

JSON representation
{
  "spreadsheetId": string,
  "replies": [
    {
      object(Response)
    }
  ],
  "updatedSpreadsheet": {
    object(Spreadsheet)
  },
}
Fields
spreadsheetId

string

The spreadsheet the updates were applied to.

replies[]

object(Response)

The reply of the updates. This maps 1:1 with the updates, although replies to some requests may be empty.

updatedSpreadsheet

object(Spreadsheet)

The spreadsheet after updates were applied. This is only set if [BatchUpdateSpreadsheetRequest.include_spreadsheet_in_response] is true.

Authorization

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets

For more information, see the Auth Guide.

Send feedback about...