# Google Sheets (/integrations/google_sheets)





{/* MANUAL-CONTENT-START:intro */}

Use [Google Sheets](https://www.google.com/sheets/about/) to read and write cell ranges, append rows, clear values, and create or inspect spreadsheets. Batch actions read, update, or clear multiple ranges; sheet-copy actions duplicate sheets within or between spreadsheets.

Provide the spreadsheet ID and range required by the selected operation. Read the returned values or update counts before passing data to later workflow steps.

{/* MANUAL-CONTENT-END */}

## OAuth scopes [#oauth-scopes]

Sim requests these scopes when someone connects a Google Sheets account. For a self-hosted deployment, register your own app with the provider using the settings below. See [Integrations and OAuth](/platform/self-hosting/integrations-oauth) for setup.

| Setting | Value |
| - | - |
| Redirect URI | `<NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/google-sheets` |
| Environment variables | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |

| Scope | Description |
| - | - |
| `https://www.googleapis.com/auth/userinfo.email` | View email address |
| `https://www.googleapis.com/auth/userinfo.profile` | View basic profile info |
| `https://www.googleapis.com/auth/drive.file` | View and manage Google Drive files you open or create with Sim |
| `https://www.googleapis.com/auth/drive` | View, edit, create, and delete all Google Drive files |

## Use the block [#usage-instructions]

Select a sheet to read, write, append, update, or clear cell values. Create spreadsheets, inspect their metadata, copy sheets, and run batch range operations.

## Actions [#actions]

### Read from Google Sheets V2 [#read-from-google-sheets-v2]

Read data from a specific sheet in a Google Sheets spreadsheet

<ReferenceDetails>
  #### Input [#input]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
  | `sheetName` | string | Yes | The name of the sheet/tab to read from |
  | `cellRange` | string | No | The cell range to read (e.g. "A1:D10"). Defaults to "A1:Z1000" if not specified. |
  | `filterColumn` | string | No | Column name (from the header row) to filter on. Filtering is applied to the rows returned by the read range (the default is A1:Z1000), not the entire sheet. If not provided, no filtering is applied. |
  | `filterValue` | string | No | Value to match against the filter column. |
  | `filterMatchType` | string | No | How to match the filter value. Text: "contains", "not\_contains", "exact", "not\_equals", "starts\_with", "ends\_with". Numeric/ordering: "gt", "gte", "lt", "lte" (numeric when both values are numbers, otherwise lexicographic). Defaults to "contains". |

  #### Output [#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 |
</ReferenceDetails>

### Write to Google Sheets V2 [#write-to-google-sheets-v2]

Write data to a specific sheet in a Google Sheets spreadsheet

<ReferenceDetails>
  #### Input [#input-1]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
  | `sheetName` | string | Yes | The name of the sheet/tab to write to |
  | `cellRange` | string | No | The cell range to write to (e.g. "A1:D10", "A1"). Defaults to "A1" if not specified. |
  | `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 |

  #### Output [#output-1]

  | 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 |
</ReferenceDetails>

### Update Google Sheets V2 [#update-google-sheets-v2]

Update data in a specific sheet in a Google Sheets spreadsheet

<ReferenceDetails>
  #### Input [#input-2]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
  | `sheetName` | string | Yes | The name of the sheet/tab to update |
  | `cellRange` | string | No | The cell range to update (e.g. "A1:D10", "A1"). Defaults to "A1" if not specified. |
  | `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 |

  #### Output [#output-2]

  | 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 |
</ReferenceDetails>

### Append to Google Sheets V2 [#append-to-google-sheets-v2]

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

<ReferenceDetails>
  #### Input [#input-3]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
  | `sheetName` | string | Yes | The name of the sheet/tab to append to |
  | `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) |

  #### Output [#output-3]

  | 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 |
</ReferenceDetails>

### Clear Google Sheets Range V2 [#clear-google-sheets-range-v2]

Clear values from a specific range in a Google Sheets spreadsheet

<ReferenceDetails>
  #### Input [#input-4]

  | 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 [#output-4]

  | 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 |
</ReferenceDetails>

### Get Spreadsheet Info V2 [#get-spreadsheet-info-v2]

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

<ReferenceDetails>
  #### Input [#input-5]

  | 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 [#output-5]

  | 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 |
</ReferenceDetails>

### Create Spreadsheet V2 [#create-spreadsheet-v2]

Create a new Google Sheets spreadsheet

<ReferenceDetails>
  #### Input [#input-6]

  | 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 [#output-6]

  | 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) |
</ReferenceDetails>

### Batch Read Google Sheets V2 [#batch-read-google-sheets-v2]

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

<ReferenceDetails>
  #### Input [#input-7]

  | 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 [#output-7]

  | 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 |
</ReferenceDetails>

### Batch Update Google Sheets V2 [#batch-update-google-sheets-v2]

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

<ReferenceDetails>
  #### Input [#input-8]

  | 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 [#output-8]

  | 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 |
</ReferenceDetails>

### Batch Clear Google Sheets V2 [#batch-clear-google-sheets-v2]

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

<ReferenceDetails>
  #### Input [#input-9]

  | 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 [#output-9]

  | 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 |
</ReferenceDetails>

### Copy Sheet V2 [#copy-sheet-v2]

Copy a sheet from one spreadsheet to another

<ReferenceDetails>
  #### Input [#input-10]

  | 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 [#output-10]

  | 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 |
</ReferenceDetails>

### Delete Rows from Google Sheets V2 [#delete-rows-from-google-sheets-v2]

Delete rows from a sheet in a Google Sheets spreadsheet

<ReferenceDetails>
  #### Input [#input-11]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
  | `sheetId` | number | Yes | The numeric ID of the sheet/tab (not the sheet name). Use Get Spreadsheet to find sheet IDs. |
  | `startIndex` | number | Yes | The start row index (0-based, inclusive) of the rows to delete |
  | `endIndex` | number | Yes | The end row index (0-based, exclusive) of the rows to delete |

  #### Output [#output-11]

  | Parameter | Type | Description |
  | - | - | - |
  | `spreadsheetId` | string | Google Sheets spreadsheet ID |
  | `sheetId` | number | The numeric ID of the sheet |
  | `deletedRowRange` | string | Description of the deleted row range |
  | `metadata` | json | Spreadsheet metadata including ID and URL |
  | ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
  | ↳ `spreadsheetUrl` | string | Spreadsheet URL |
</ReferenceDetails>

### Delete Sheet V2 [#delete-sheet-v2]

Delete a sheet/tab from a Google Sheets spreadsheet

<ReferenceDetails>
  #### Input [#input-12]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `spreadsheetId` | string | Yes | Google Sheets spreadsheet ID |
  | `sheetId` | number | Yes | The numeric ID of the sheet/tab to delete (not the sheet name). Use Get Spreadsheet to find sheet IDs. |

  #### Output [#output-12]

  | Parameter | Type | Description |
  | - | - | - |
  | `spreadsheetId` | string | Google Sheets spreadsheet ID |
  | `deletedSheetId` | number | The numeric ID of the deleted sheet |
  | `metadata` | json | Spreadsheet metadata including ID and URL |
  | ↳ `spreadsheetId` | string | Google Sheets spreadsheet ID |
  | ↳ `spreadsheetUrl` | string | Spreadsheet URL |
</ReferenceDetails>

### Delete Spreadsheet V2 [#delete-spreadsheet-v2]

Permanently delete a Google Sheets spreadsheet using the Google Drive API

<ReferenceDetails>
  #### Input [#input-13]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `spreadsheetId` | string | Yes | The ID of the Google Sheets spreadsheet to delete |

  #### Output [#output-13]

  | Parameter | Type | Description |
  | - | - | - |
  | `spreadsheetId` | string | The ID of the deleted spreadsheet |
  | `deleted` | boolean | Whether the spreadsheet was successfully deleted |
</ReferenceDetails>

## Triggers [#triggers]

A trigger starts a workflow when a supported event occurs in this service.

These triggers poll for new data on a schedule.

### Google Sheets New Row Trigger [#google-sheets-new-row-trigger]

Triggers when new rows are added to a Google Sheet

#### Configuration [#configuration]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `triggerCredentials` | string | Yes | Connect your Google account to access Google Sheets. |
| `spreadsheetId` | file-selector | Yes | The spreadsheet to monitor for new rows. |
| `manualSpreadsheetId` | string | Yes | The spreadsheet to monitor for new rows. |
| `sheetName` | sheet-selector | Yes | The sheet tab to monitor for new rows. |
| `manualSheetName` | string | Yes | The sheet tab to monitor for new rows. |
| `valueRenderOption` | string | No | How values are rendered. Formatted returns display strings, Unformatted returns raw numbers/booleans, Formula returns the formula text. |
| `dateTimeRenderOption` | string | No | How dates and times are rendered. Only applies when Value Render is not "Formatted Value". |

#### Output [#output-14]

| Parameter | Type | Description |
| - | - | - |
| `row` | json | Row data mapped to column headers from row 1 |
| `rawRow` | json | Raw row values as an array |
| `headers` | json | Column headers from row 1 |
| `rowNumber` | number | The 1-based row number of the new row |
| `spreadsheetId` | string | The spreadsheet ID |
| `sheetName` | string | The sheet tab name |
| `timestamp` | string | Event timestamp in ISO format |