> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt
> Use this file to discover all available pages before exploring further.

# spreadsheets_batch_update

> Apply a list of updates to a spreadsheet. Each request sets exactly one kind of edit — add_sheet, update_cells, merge_cells and so on. Requests are applied in order, atomically: if any is invalid, none are applied.

<div className="tool-route"><span className="tool-row-method" data-method="POST">POST</span><code>{"https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}:batchUpdate"}</code></div>

```python gsheets_spreadsheets_batch_update.py theme={null}
from charter.packs import gsheets

result = await gsheets.spreadsheets_batch_update.ainvoke({"spreadsheetId": ..., "requests": ...})
```

<Note>
  Requires `https://www.googleapis.com/auth/spreadsheets`. Costs 1 against the provider's own quota.
</Note>

<Warning>
  This tool's JSON schema is 190 KB, because `requests` carries 74 kinds of edit behind one method.
  That is more context than most tasks. Narrow it at the call site
  with [`Tool.derived`](/charter/charter/reference/tool#tool-derived):

  ```python theme={null}
  narrowed = gsheets.spreadsheets_batch_update.derived(
      name="spreadsheets_batch_update_narrowed",
      keep={"update_spreadsheet_properties", "update_sheet_properties", "update_dimension_properties"},
  )
  ```

  Three of the 74 are kept here. Which ones your agent needs is yours to pick. The tool underneath is unchanged.
  See [Projections](/charter/charter/tools/projections).
</Warning>

## Path parameters

<div className="reference-table">
  | Field                                                                 | Type     | Description                              |
  | --------------------------------------------------------------------- | -------- | ---------------------------------------- |
  | `spreadsheetId` <span className="required" title="required">\*</span> | `string` | The spreadsheet to apply the updates to. |
</div>

## Body

<div className="reference-table">
  | Field                                                            | Type                                                                             | Description                                                                                                                                                                                                                                                              |
  | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `requests` <span className="required" title="required">\*</span> | [Request](/charter/charter/packs/gsheets/spreadsheets/objects#request)\[]                | A list of updates to apply to the spreadsheet. Requests will be applied in the order they are specified. Each Request sets exactly one kind of update. 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 includeSpreadsheetInResponse is 'true'.                                                                                                                                                       |
  | `responseIncludeGridData`                                        | `boolean`                                                                        | True if grid data should be returned. Meaningful only if includeSpreadsheetInResponse is 'true'. This parameter is ignored if a field mask was set in the request.                                                                                                       |
  | `commentsViewMode`                                               | [CommentsViewMode](/charter/charter/packs/gsheets/spreadsheets/objects#commentsviewmode) | The comments view mode to apply to the spreadsheet. This allows viewing the spreadsheet with comments omitted or included. If one is not specified, COMMENTS\_VIEW\_MODE\_OMITTED is used. Meaningful only if includeSpreadsheetInResponse is 'true'. Developer Preview. |
</div>