---
title: Google Sheets
description: Read, write, and update data with sheet selection
---

import { BlockInfoCard } from "@/components/ui/block-info-card"

<BlockInfoCard 
  type="google_sheets_v2"
  color="#E0E0E0"
/>

{/* MANUAL-CONTENT-START:intro */}
[Google Sheets](https://www.google.com/sheets/about/) is a cloud-based spreadsheet platform that allows teams and individuals to create, edit, and collaborate on spreadsheets in real-time. Widely used for data tracking, reporting, and lightweight database needs, Google Sheets integrates with many tools and services.

With the Google Sheets integration in Sim, you can:

- **Read data**: Retrieve cell values from specific ranges in a spreadsheet
- **Write data**: Write values to specific cell ranges
- **Update data**: Modify existing cell values in a spreadsheet
- **Append rows**: Add new rows of data to the end of a sheet
- **Clear ranges**: Remove data from specific cell ranges
- **Manage spreadsheets**: Create new spreadsheets or retrieve metadata about existing ones
- **Batch operations**: Perform batch read, update, and clear operations across multiple ranges
- **Copy sheets**: Duplicate sheets within or between spreadsheets

In Sim, the Google Sheets integration enables your agents to read from, write to, and manage spreadsheets as part of automated workflows. This is ideal for automated reporting, data synchronization, record-keeping, and building data pipelines that use spreadsheets as a collaborative data layer.
{/* MANUAL-CONTENT-END */}


## Usage Instructions

Integrate Google Sheets into the workflow with explicit sheet selection. Can read, write, append, update, clear data, create spreadsheets, get spreadsheet info, and copy sheets.



## Tools

### `google_sheets_read`

Read data from a specific sheet in a Google Sheets spreadsheet

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `spreadsheetId` | string | Yes | The ID of the spreadsheet \(found in the URL: docs.google.com/spreadsheets/d/\{SPREADSHEET_ID\}/edit\). |
| `range` | string | No | The A1 notation range to read \(e.g. "Sheet1!A1:D10", "A1:B5"\). Defaults to first sheet A1:Z1000 if not specified. |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `sheetName` | string | Name of the sheet that was read |
| `range` | string | The range of cells that was read |
| `values` | array | The cell values as a 2D array |
| `metadata` | json | Spreadsheet metadata including ID and URL |
|   ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
|   ↳ `spreadsheetUrl` | string | Spreadsheet URL |

### `google_sheets_write`

Write data to a specific sheet in a Google Sheets spreadsheet

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `spreadsheetId` | string | Yes | The ID of the spreadsheet |
| `range` | string | No | The A1 notation range to write to \(e.g. "Sheet1!A1:D10", "A1:B5"\) |
| `values` | array | Yes | The data to write as a 2D array \(e.g. \[\["Name", "Age"\], \["Alice", 30\], \["Bob", 25\]\]\) or array of objects. |
| `valueInputOption` | string | No | The format of the data to write |
| `includeValuesInResponse` | boolean | No | Whether to include the written values in the response |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `updatedRange` | string | Range of cells that were updated |
| `updatedRows` | number | Number of rows updated |
| `updatedColumns` | number | Number of columns updated |
| `updatedCells` | number | Number of cells updated |
| `metadata` | json | Spreadsheet metadata including ID and URL |
|   ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
|   ↳ `spreadsheetUrl` | string | Spreadsheet URL |

### `google_sheets_update`

Update data in a specific sheet in a Google Sheets spreadsheet

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `spreadsheetId` | string | Yes | The ID of the spreadsheet to update |
| `range` | string | No | The A1 notation range to update \(e.g. "Sheet1!A1:D10", "A1:B5"\) |
| `values` | array | Yes | The data to update as a 2D array \(e.g. \[\["Name", "Age"\], \["Alice", 30\]\]\) or array of objects. |
| `valueInputOption` | string | No | The format of the data to update |
| `includeValuesInResponse` | boolean | No | Whether to include the updated values in the response |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `updatedRange` | string | Range of cells that were updated |
| `updatedRows` | number | Number of rows updated |
| `updatedColumns` | number | Number of columns updated |
| `updatedCells` | number | Number of cells updated |
| `metadata` | json | Spreadsheet metadata including ID and URL |
|   ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
|   ↳ `spreadsheetUrl` | string | Spreadsheet URL |

### `google_sheets_append`

Append data to the end of a specific sheet in a Google Sheets spreadsheet

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `spreadsheetId` | string | Yes | The ID of the spreadsheet to append to |
| `range` | string | No | The A1 notation range to append after \(e.g. "Sheet1", "Sheet1!A:D"\) |
| `values` | array | Yes | The data to append as a 2D array \(e.g. \[\["Alice", 30\], \["Bob", 25\]\]\) or array of objects. |
| `valueInputOption` | string | No | The format of the data to append |
| `insertDataOption` | string | No | How to insert the data \(OVERWRITE or INSERT_ROWS\) |
| `includeValuesInResponse` | boolean | No | Whether to include the appended values in the response |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `tableRange` | string | Range of the table where data was appended |
| `updatedRange` | string | Range of cells that were updated |
| `updatedRows` | number | Number of rows updated |
| `updatedColumns` | number | Number of columns updated |
| `updatedCells` | number | Number of cells updated |
| `metadata` | json | Spreadsheet metadata including ID and URL |
|   ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
|   ↳ `spreadsheetUrl` | string | Spreadsheet URL |

### `google_sheets_clear`

Clear values from a specific range in a Google Sheets spreadsheet

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
| `sheetName` | string | Yes | The name of the sheet/tab to clear |
| `cellRange` | string | No | The cell range to clear \(e.g. "A1:D10"\). Clears entire sheet if not specified. |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `clearedRange` | string | The range that was cleared |
| `sheetName` | string | Name of the sheet that was cleared |
| `metadata` | json | Spreadsheet metadata including ID and URL |
|   ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
|   ↳ `spreadsheetUrl` | string | Spreadsheet URL |

### `google_sheets_get_spreadsheet`

Get metadata about a Google Sheets spreadsheet including title and sheet list

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
| `includeGridData` | boolean | No | Whether to include grid data \(cell values\). Defaults to false. |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `spreadsheetId` | string | The spreadsheet ID |
| `title` | string | The title of the spreadsheet |
| `locale` | string | The locale of the spreadsheet |
| `timeZone` | string | The time zone of the spreadsheet |
| `spreadsheetUrl` | string | URL to the spreadsheet |
| `sheets` | array | List of sheets in the spreadsheet |
|   ↳ `sheetId` | number | The sheet ID |
|   ↳ `title` | string | The sheet title/name |
|   ↳ `index` | number | The sheet index \(position\) |
|   ↳ `rowCount` | number | Number of rows in the sheet |
|   ↳ `columnCount` | number | Number of columns in the sheet |
|   ↳ `hidden` | boolean | Whether the sheet is hidden |

### `google_sheets_create_spreadsheet`

Create a new Google Sheets spreadsheet

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `title` | string | Yes | The title of the new spreadsheet |
| `sheetTitles` | json | No | Array of sheet names to create \(e.g., \["Sheet1", "Data", "Summary"\]\). Defaults to a single "Sheet1". |
| `locale` | string | No | The locale of the spreadsheet \(e.g., "en_US"\) |
| `timeZone` | string | No | The time zone of the spreadsheet \(e.g., "America/New_York"\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `spreadsheetId` | string | The ID of the created spreadsheet |
| `title` | string | The title of the created spreadsheet |
| `spreadsheetUrl` | string | URL to the created spreadsheet |
| `sheets` | array | List of sheets created in the spreadsheet |
|   ↳ `sheetId` | number | The sheet ID |
|   ↳ `title` | string | The sheet title/name |
|   ↳ `index` | number | The sheet index \(position\) |

### `google_sheets_batch_get`

Read multiple ranges from a Google Sheets spreadsheet in a single request

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
| `ranges` | json | Yes | Array of ranges to read \(e.g., \["Sheet1!A1:D10", "Sheet2!A1:B5"\]\). Each range should include sheet name. |
| `majorDimension` | string | No | The major dimension of values: "ROWS" \(default\) or "COLUMNS" |
| `valueRenderOption` | string | No | How values should be rendered: "FORMATTED_VALUE" \(default\), "UNFORMATTED_VALUE", or "FORMULA" |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `spreadsheetId` | string | The spreadsheet ID |
| `valueRanges` | array | Array of value ranges read from the spreadsheet |
|   ↳ `range` | string | The range that was read |
|   ↳ `majorDimension` | string | Major dimension \(ROWS or COLUMNS\) |
|   ↳ `values` | array | The cell values as a 2D array |
| `metadata` | json | Spreadsheet metadata including ID and URL |
|   ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
|   ↳ `spreadsheetUrl` | string | Spreadsheet URL |

### `google_sheets_batch_update`

Update multiple ranges in a Google Sheets spreadsheet in a single request

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
| `data` | json | Yes | Array of value ranges to update. Each item should have "range" \(e.g., "Sheet1!A1:D10"\) and "values" \(2D array\). |
| `valueInputOption` | string | No | How input data should be interpreted: "RAW" or "USER_ENTERED" \(default\). USER_ENTERED parses formulas. |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `spreadsheetId` | string | The spreadsheet ID |
| `totalUpdatedRows` | number | Total number of rows updated |
| `totalUpdatedColumns` | number | Total number of columns updated |
| `totalUpdatedCells` | number | Total number of cells updated |
| `totalUpdatedSheets` | number | Total number of sheets updated |
| `responses` | array | Array of update responses for each range |
|   ↳ `spreadsheetId` | string | The spreadsheet ID |
|   ↳ `updatedRange` | string | The range that was updated |
|   ↳ `updatedRows` | number | Number of rows updated in this range |
|   ↳ `updatedColumns` | number | Number of columns updated in this range |
|   ↳ `updatedCells` | number | Number of cells updated in this range |
| `metadata` | json | Spreadsheet metadata including ID and URL |
|   ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
|   ↳ `spreadsheetUrl` | string | Spreadsheet URL |

### `google_sheets_batch_clear`

Clear multiple ranges in a Google Sheets spreadsheet in a single request

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
| `ranges` | json | Yes | Array of ranges to clear \(e.g., \["Sheet1!A1:D10", "Sheet2!A1:B5"\]\). Each range should include sheet name. |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `spreadsheetId` | string | The spreadsheet ID |
| `clearedRanges` | array | Array of ranges that were cleared |
| `metadata` | json | Spreadsheet metadata including ID and URL |
|   ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
|   ↳ `spreadsheetUrl` | string | Spreadsheet URL |

### `google_sheets_copy_sheet`

Copy a sheet from one spreadsheet to another

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `sourceSpreadsheetId` | string | Yes | Source Google Sheets spreadsheet ID |
| `sheetId` | number | Yes | The ID of the sheet to copy \(numeric ID, not the sheet name\). Use Get Spreadsheet to find sheet IDs. |
| `destinationSpreadsheetId` | string | Yes | The ID of the destination spreadsheet where the sheet will be copied |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `sheetId` | number | The ID of the newly created sheet in the destination |
| `title` | string | The title of the copied sheet |
| `index` | number | The index \(position\) of the copied sheet |
| `sheetType` | string | The type of the sheet \(GRID, CHART, etc.\) |
| `destinationSpreadsheetId` | string | The ID of the destination spreadsheet |
| `destinationSpreadsheetUrl` | string | URL to the destination spreadsheet |


