> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/google-sheets.md).

# Google Sheets

Google Sheets is a spreadsheet program included as part of Google's free, web-based office suite.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector                 | Authentication |
| ------------------------- | -------------- |
| Google Sheets             | OAuth sign-in  |
| Google Sheets (Workspace) | OAuth sign-in  |

#### Google Sheets

Connect to Google Sheets to read and write spreadsheet data. Supports reading, writing, updating cells, and managing spreadsheets.

**Set up in Google Sheets**

1. Sign in to your Google account in the window that opens.
2. Review and authorize the requested permissions to read and write your spreadsheet data.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Google Sheets**.
2. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

StackAI obtains the OAuth credentials during sign-in. You do not need to paste an access token or refresh token.

**Provider documentation:** [Setup reference](https://www.google.com/sheets/about/).

#### Google Sheets (Workspace)

Connect to Google Sheets using Google Workspace OAuth2 authentication. Supports reading and writing spreadsheet data.

**Set up in Google Sheets**

1. Sign in with your Google Workspace account in the window that opens.
2. Review and authorize the requested permissions to read and write spreadsheet data.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Google Sheets (Workspace)**.
2. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

StackAI obtains the OAuth credentials during sign-in. You do not need to paste an access token or refresh token.

**Provider documentation:** [Setup reference](https://www.google.com/sheets/about/).

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

#### Detailed setup guides

* [Connect Google Sheets and configure sheet access](https://docs.stackai.com/integrations/catalog/google-sheets/connect-google-sheets-and-configure-sheet-access.md)
* [Set up Google OAuth credentials](https://docs.stackai.com/integrations/catalog/google-workspace/set-up-google-oauth-credentials.md)

## Use an action

1. Add the required **Google Sheets** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Write to Sheet

Append rows to a Google Sheet, or overwrite a range from a CSV URL

**Inputs**

| Field              | Type            | Required | Description                                                                                                                                                                                                                                                                                                                           |
| ------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet        | select (string) | Yes      | Select the Google Spreadsheet to write data to, or paste its ID. Options load from the selected connection.                                                                                                                                                                                                                           |
| Sheet              | select (string) | Yes      | Select the sheet/tab to write data to. Options load from the selected connection.                                                                                                                                                                                                                                                     |
| Data Format        | select (string) | No       | Choose whether to enter data manually or use a CSV URL. Available values: Manual Entry, CSV File Upload. Default: manual.                                                                                                                                                                                                             |
| Data               | textarea        | No       | Data to append as one or more rows. Provide a JSON object for a single row, or a JSON array of objects for multiple rows (e.g., \[{"Name": "John"}, {"Name": "Jane"}]). Keys that are not already column headers are added to the sheet as new columns. Matching is case-sensitive, so 'name' and 'Name' become two separate columns. |
| CSV URL            | string          | No       | URL of a CSV file to write into the sheet, starting at Starting Cell. The CSV overwrites the cells it covers and does not add rows. Cells outside the CSV are not cleared. Required when Data Format is CSV.                                                                                                                          |
| Starting Cell      | string          | No       | Top-left cell where the CSV is written (e.g., A1). Required when Data Format is CSV.                                                                                                                                                                                                                                                  |
| Value Input Option | select (string) | No       | How input data should be interpreted (only used for manual entry). Available values: RAW - Store as literal text (no parsing), USER\_ENTERED - Parse formulas, numbers, and dates (recommended).                                                                                                                                      |

**Outputs**

| Field         | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| Status        | string | Status of the operation.                       |
| Updated Range | string | The range that was updated in the spreadsheet. |
| Message       | string | Message about the operation.                   |

#### Read from Sheet

Read data from a Google Sheet (e.g., Sheet1, range A1:B10)

> **Deprecated:** This action will soon be deprecated. Please use 'Get Sheet Data' instead.

**Inputs**

| Field                | Type            | Required | Description                                                                                                                                                                               |
| -------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet          | select (string) | Yes      | Select the Google Spreadsheet to read data from, or paste its ID. Options load from the selected connection.                                                                              |
| Sheet                | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.                                                                                          |
| Range (Optional)     | string          | No       | Optional range in A1 notation (e.g., A1:B10, A:C, 1:5) - leave empty for all data. Default: .                                                                                             |
| Include Headers      | boolean         | No       | Whether to treat the first row as column headers (true to use first row as headers, false otherwise). Default: true.                                                                      |
| Filtering (Optional) | string          | No       | Optional natural language filter. Only rows matching this description are returned. Examples: 'rows where Name is Sam', 'where Status equals Done', 'Amount greater than 100'. Default: . |

**Outputs**

| Field     | Type    | Description                   |
| --------- | ------- | ----------------------------- |
| Status    | string  | Status of the operation.      |
| Data      | object  | The data read from the sheet. |
| Row Count | integer | Number of rows read.          |
| Message   | string  | Message about the operation.  |

#### Update Sheet

Update data in a Google Sheet (by row, criteria, or range)

**Inputs**

| Field           | Type            | Required | Description                                                                                                                                                                               |
| --------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet     | select (string) | Yes      | Select the Google Spreadsheet containing the data to update. Options load from the selected connection.                                                                                   |
| Sheet           | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.                                                                                          |
| Update Method   | select (string) | Yes      | Choose how to identify rows to update. By row number (e.g. row 5), by criteria (e.g. column and value) or by range (e.g. A5:A10). Available values: By row number, By criteria, By range. |
| Row Number      | integer         | No       | Row number to update (e.g., 5 for row 5, 10 for row 10). Needs update method set to 'By row number'. Default: 0.                                                                          |
| Criteria Column | string          | No       | Column name for matching criteria (e.g., Name, Email, ID). Needs update method set to 'By criteria'. Default: .                                                                           |
| Criteria Value  | string          | No       | Value to match in the Criteria Column (e.g., Jason, <jason@email.com>, 12345). Needs update method set to 'By criteria'. Default: .                                                       |
| Range           | string          | No       | Range specification (e.g., A1:C5, B2:D10, A:A for entire column). Needs update method set to 'By range'. Default: .                                                                       |
| Updates         | textarea        | Yes      | JSON object with column names and new values (e.g., {"Name": "John Smith", "Age": "30"}).                                                                                                 |

**Outputs**

| Field          | Type    | Description                  |
| -------------- | ------- | ---------------------------- |
| Status         | string  | Status of the operation.     |
| Updated Ranges | object  | Ranges that were updated.    |
| Rows Updated   | integer | Number of rows updated.      |
| Message        | string  | Message about the operation. |

#### Delete Row

Delete a specific row from a Google Sheet by row number

> **Deprecated:** This action will soon be deprecated. Please use 'Remove Row' instead.

**Inputs**

| Field       | Type            | Required | Description                                                                                            |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet containing the row to delete. Options load from the selected connection. |
| Sheet       | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.       |
| Row Number  | integer         | Yes      | Row number to delete (e.g., 2, 5, 10).                                                                 |

**Outputs**

| Field              | Type    | Description                               |
| ------------------ | ------- | ----------------------------------------- |
| Success            | boolean | Whether the row was successfully deleted. |
| Deleted Row Number | integer | The row number that was deleted.          |
| Status Message     | string  | Success or error message.                 |

#### Remove Row

Delete a specific row from a Google Sheet by row number

**Inputs**

| Field       | Type            | Required | Description                                                                                            |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet containing the row to delete. Options load from the selected connection. |
| Sheet       | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.       |
| Row Number  | integer         | Yes      | Row number to delete (e.g., 2, 5, 10).                                                                 |

**Outputs**

| Field              | Type    | Description                               |
| ------------------ | ------- | ----------------------------------------- |
| Success            | boolean | Whether the row was successfully deleted. |
| Deleted Row Number | integer | The row number that was deleted.          |
| Status Message     | string  | Success or error message.                 |

#### Find Row

Find rows in a Google Sheet by searching for a value in a specific column

**Inputs**

| Field            | Type            | Required | Description                                                                                                           |
| ---------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet      | select (string) | Yes      | Select the Google Spreadsheet to search in, or paste its ID. Options load from the selected connection.               |
| Sheet            | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.                      |
| Column           | select (string) | Yes      | The column to search in (e.g., 'Company', 'Email', 'Name'). Options load from the selected connection.                |
| Search Value     | string          | Yes      | The value to search for in the specified column.                                                                      |
| Include Row Data | boolean         | No       | Whether to include the full row data for each match (true to include full row data, false otherwise). Default: false. |

**Outputs**

| Field         | Type    | Description                                               |
| ------------- | ------- | --------------------------------------------------------- |
| Found         | boolean | Whether any matching rows were found.                     |
| Match Count   | integer | Number of rows that match the search criteria.            |
| Matching Rows | object  | List of matching rows with row numbers and optional data. |
| Message       | string  | Status message about the search operation.                |

#### Get Row by Index

Get a specific row from a Google Sheet by row number/index

> **Deprecated:** This action will soon be deprecated. Please use 'Get Row' instead.

**Inputs**

| Field           | Type            | Required | Description                                                                                        |
| --------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------- |
| Spreadsheet     | select (string) | Yes      | Select the Google Spreadsheet to retrieve the row from. Options load from the selected connection. |
| Sheet           | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.   |
| Row Index       | integer         | Yes      | Row number to retrieve (e.g., 2, 5, 10).                                                           |
| Include Headers | boolean         | No       | Whether to use column headers as keys (default: true).                                             |

**Outputs**

| Field          | Type    | Description                          |
| -------------- | ------- | ------------------------------------ |
| Row Index      | integer | The row index that was retrieved.    |
| Row Exists     | boolean | Whether the row exists and has data. |
| Row Data       | object  | The row data as key-value pairs.     |
| Status Message | string  | Success or error message.            |

#### Get Row

Get a specific row from a Google Sheet by row number/index

**Inputs**

| Field       | Type            | Required | Description                                                                                        |
| ----------- | --------------- | -------- | -------------------------------------------------------------------------------------------------- |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet to retrieve the row from. Options load from the selected connection. |
| Sheet       | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.   |
| Row Index   | integer         | Yes      | Row number to retrieve (e.g., 2, 5, 10).                                                           |

**Outputs**

| Field          | Type    | Description                          |
| -------------- | ------- | ------------------------------------ |
| Row Index      | integer | The row index that was retrieved.    |
| Row Exists     | boolean | Whether the row exists and has data. |
| Row Data       | object  | The row data as key-value pairs.     |
| Status Message | string  | Success or error message.            |

#### Update Cell

Update a specific cell value in a Google Sheet by cell address

**Inputs**

| Field        | Type            | Required | Description                                                                                             |
| ------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| Spreadsheet  | select (string) | Yes      | Select the Google Spreadsheet containing the cell to update. Options load from the selected connection. |
| Sheet        | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.        |
| Cell Address | string          | Yes      | Cell address in A1 notation (e.g., A1, B2, C10, AA5).                                                   |
| Value        | string          | Yes      | New value for the cell (text, number, or formula like =SUM(A1:A10)).                                    |

**Outputs**

| Field          | Type   | Description                        |
| -------------- | ------ | ---------------------------------- |
| Updated Range  | string | The range that was updated.        |
| Cell Address   | string | The cell address that was updated. |
| New Value      | string | The new value that was set.        |
| Status Message | string | Success message with details.      |

#### Create Spreadsheet

Create a new Google Spreadsheet with a specified title

**Inputs**

| Field              | Type            | Required | Description                                                                                                     |
| ------------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| Spreadsheet Title  | string          | Yes      | Enter the title for the new spreadsheet (e.g., 'Sales Data 2024', 'Customer List', 'Project Tasks').            |
| Initial Sheet Name | string          | No       | Name for the first sheet/tab (optional, defaults to 'Sheet1').                                                  |
| Drive              | select (string) | No       | Select a Shared Drive, or leave as My Drive. Options load from the selected connection. Default: my-drive.      |
| Destination Folder | select (string) | No       | Optional destination folder. Leave empty to create in My Drive root. Options load from the selected connection. |

**Outputs**

| Field           | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| Spreadsheet ID  | string | The unique ID of the created spreadsheet. |
| Spreadsheet URL | string | The web URL to access the spreadsheet.    |
| Title           | string | The title of the created spreadsheet.     |
| Status Message  | string | Success message with details.             |

#### Create Sheet

Create a new sheet/tab in an existing Google Spreadsheet

**Inputs**

| Field         | Type            | Required | Description                                                                                                                            |
| ------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet   | select (string) | Yes      | Select the Google Spreadsheet where the new sheet will be created. Options load from the selected connection.                          |
| Sheet Name    | string          | Yes      | Name for the new sheet/tab to create.                                                                                                  |
| Data Format   | select (string) | No       | Choose whether to create an empty sheet or populate it from a CSV URL. Available values: Empty Sheet, CSV File Upload. Default: empty. |
| CSV URL       | string          | No       | URL of a CSV file to download and populate the new sheet with data.                                                                    |
| Starting Cell | string          | No       | Starting cell address for CSV data (e.g., A1). Required when using CSV URL.                                                            |

**Outputs**

| Field           | Type   | Description                             |
| --------------- | ------ | --------------------------------------- |
| Spreadsheet ID  | string | The unique ID of the spreadsheet.       |
| Spreadsheet URL | string | The web URL to access the spreadsheet.  |
| Sheet ID        | string | The unique ID of the created sheet/tab. |
| Sheet Name      | string | The name of the created sheet/tab.      |
| Status Message  | string | Success message with details.           |

#### List Column Headers

Get the column headers from the first row of a Google Sheet

**Inputs**

| Field       | Type            | Required | Description                                                                                                         |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet containing the sheet to read headers from. Options load from the selected connection. |
| Sheet       | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.                    |

**Outputs**

| Field          | Type    | Description                                |
| -------------- | ------- | ------------------------------------------ |
| Column Headers | object  | List of column headers from the first row. |
| Header Count   | integer | Number of column headers found.            |
| Status Message | string  | Success message with details.              |

#### Create Column Headers

Create column headers in the first row of a Google Sheet

**Inputs**

| Field       | Type            | Required | Description                                                                                                     |
| ----------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet where headers will be created. Options load from the selected connection.         |
| Sheet       | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.                |
| Headers     | textarea        | Yes      | Column headers as JSON array or comma-separated text (e.g., '\["Name", "Email", "Age"]' or 'Name, Email, Age'). |

**Outputs**

| Field           | Type    | Description                           |
| --------------- | ------- | ------------------------------------- |
| Updated Range   | string  | The range where headers were created. |
| Created Headers | object  | The column headers that were created. |
| Header Count    | integer | Number of headers created.            |
| Status Message  | string  | Success message with details.         |

#### List Worksheets

List all worksheets/sheets in a Google Spreadsheet with their details

> **Deprecated:** This action will soon be deprecated. Please use 'List Sheets' instead.

**Inputs**

| Field       | Type            | Required | Description                                                                                       |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------- |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet to list worksheets from. Options load from the selected connection. |

**Outputs**

| Field             | Type    | Description                                   |
| ----------------- | ------- | --------------------------------------------- |
| Worksheets        | object  | List of worksheets/sheets with their details. |
| Worksheet Count   | integer | Number of worksheets/sheets found.            |
| Spreadsheet Title | string  | The title of the spreadsheet.                 |
| Status Message    | string  | Success message with details.                 |

#### List Sheets

List all worksheets/sheets in a Google Spreadsheet with their details

**Inputs**

| Field       | Type            | Required | Description                                                                                                        |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet to list worksheets from, or paste its ID. Options load from the selected connection. |

**Outputs**

| Field             | Type    | Description                                   |
| ----------------- | ------- | --------------------------------------------- |
| Worksheets        | object  | List of worksheets/sheets with their details. |
| Worksheet Count   | integer | Number of worksheets/sheets found.            |
| Spreadsheet Title | string  | The title of the spreadsheet.                 |
| Status Message    | string  | Success message with details.                 |

#### Get Spreadsheet Details

Get detailed information about a Google Spreadsheet including sheets, dimensions, and metadata

> **Deprecated:** This action will soon be deprecated. Please use 'Get Spreadsheet' instead.

**Inputs**

| Field       | Type            | Required | Description                                                                                        |
| ----------- | --------------- | -------- | -------------------------------------------------------------------------------------------------- |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet to retrieve details from. Options load from the selected connection. |

**Outputs**

| Field          | Type    | Description                               |
| -------------- | ------- | ----------------------------------------- |
| Spreadsheet ID | string  | The unique ID of the spreadsheet.         |
| Title          | string  | The title of the spreadsheet.             |
| Locale         | string  | The locale/language setting.              |
| Time Zone      | string  | The time zone setting.                    |
| Sheet Count    | integer | Number of sheets/tabs in the spreadsheet. |
| Sheets         | object  | List of sheets with their details.        |
| Status Message | string  | Success message with details.             |

#### Get Spreadsheet

Get detailed information about a Google Spreadsheet including sheets, dimensions, and metadata

**Inputs**

| Field       | Type            | Required | Description                                                                                                         |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet to retrieve details from, or paste its ID. Options load from the selected connection. |

**Outputs**

| Field          | Type    | Description                               |
| -------------- | ------- | ----------------------------------------- |
| Spreadsheet ID | string  | The unique ID of the spreadsheet.         |
| Title          | string  | The title of the spreadsheet.             |
| Locale         | string  | The locale/language setting.              |
| Time Zone      | string  | The time zone setting.                    |
| Sheet Count    | integer | Number of sheets/tabs in the spreadsheet. |
| Sheets         | object  | List of sheets with their details.        |
| Status Message | string  | Success message with details.             |

#### Update Row

Update one or more columns in an existing row by row number

**Inputs**

| Field       | Type            | Required | Description                                                                                                             |
| ----------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet containing the row to update, or paste its ID. Options load from the selected connection. |
| Sheet       | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.                        |
| Row Number  | integer         | Yes      | The row number to update (1-indexed, must exist).                                                                       |
| Updates     | object          | Yes      | Updates to apply as either an object input or a JSON string object (e.g., {"Status": "Completed", "Score": 95}).        |

**Outputs**

| Field            | Type    | Description                                     |
| ---------------- | ------- | ----------------------------------------------- |
| Status           | string  | Status of the update operation.                 |
| Row Number       | integer | The row number that was updated.                |
| Columns Affected | array   | List of column names that were updated.         |
| Message          | string  | Descriptive message about the update operation. |

#### Delete Worksheet

Delete a worksheet/tab from a Google Spreadsheet

**Inputs**

| Field       | Type            | Required | Description                                                                                                                   |
| ----------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet containing the worksheet to delete, or paste its ID. Options load from the selected connection. |
| Sheet       | select (string) | Yes      | Select the worksheet/tab to delete. Options load from the selected connection.                                                |

**Outputs**

| Field              | Type   | Description                                         |
| ------------------ | ------ | --------------------------------------------------- |
| Deleted Sheet Name | string | The name of the deleted worksheet.                  |
| Spreadsheet ID     | string | The spreadsheet ID where the worksheet was deleted. |
| Message            | string | Status message about the delete operation.          |

#### Copy Worksheet

Copy a worksheet within or to another Google Spreadsheet

**Inputs**

| Field                   | Type            | Required | Description                                                                                                                                                 |
| ----------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source Spreadsheet      | select (string) | Yes      | Select the Google Spreadsheet containing the worksheet to copy, or paste its ID. Options load from the selected connection.                                 |
| Source Sheet            | select (string) | Yes      | Select the worksheet/tab to copy. Options load from the selected connection.                                                                                |
| Destination Spreadsheet | select (string) | No       | Select the destination spreadsheet, or paste its ID (optional, leave empty to copy within the same spreadsheet). Options load from the selected connection. |

**Outputs**

| Field                       | Type    | Description                                            |
| --------------------------- | ------- | ------------------------------------------------------ |
| New Sheet ID                | integer | The ID of the newly created worksheet.                 |
| New Sheet Title             | string  | The title of the newly created worksheet.              |
| Destination Spreadsheet ID  | string  | The spreadsheet ID where the copy was created.         |
| Destination Spreadsheet URL | string  | URL to the destination spreadsheet with the new sheet. |
| Message                     | string  | Status message about the copy operation.               |

#### Insert Note

Insert or replace a note on a specific cell

**Inputs**

| Field        | Type            | Required | Description                                                                                                    |
| ------------ | --------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| Spreadsheet  | select (string) | Yes      | Select the Google Spreadsheet containing the cell, or paste its ID. Options load from the selected connection. |
| Sheet        | select (string) | Yes      | Select the worksheet/tab containing the cell. Options load from the selected connection.                       |
| Cell Address | string          | Yes      | Cell address in A1 notation (e.g., 'A1', 'B5', 'AA100').                                                       |
| Note Text    | string          | Yes      | The text content of the note to insert.                                                                        |

**Outputs**

| Field        | Type   | Description                                   |
| ------------ | ------ | --------------------------------------------- |
| Cell Address | string | The cell address where the note was inserted. |
| Note Text    | string | The note text that was inserted.              |
| Message      | string | Status message about the note insertion.      |

#### Get Sheet Data

Get data from a Google Sheet

**Inputs**

| Field            | Type            | Required | Description                                                                                                  |
| ---------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| Spreadsheet      | select (string) | Yes      | Select the Google Spreadsheet to read data from, or paste its ID. Options load from the selected connection. |
| Sheet            | select (string) | Yes      | Select the specific sheet/tab within the spreadsheet. Options load from the selected connection.             |
| Range (Optional) | string          | No       | Optional range in A1 notation (e.g., 'A1:D10', 'A:C', '1:5'). Leave empty to read all data.                  |

**Outputs**

| Field     | Type    | Description                      |
| --------- | ------- | -------------------------------- |
| Data      | array   | The rows of data from the sheet. |
| Row Count | integer | Number of data rows returned.    |
| Columns   | array   | List of column headers.          |
| Message   | string  | Status message.                  |

#### Get Cell

Get the value of a single cell in a Google Sheet

**Inputs**

| Field       | Type            | Required | Description                                                                                |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------ |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet, or paste its ID. Options load from the selected connection. |
| Sheet       | select (string) | Yes      | Select the specific sheet/tab. Options load from the selected connection.                  |
| Cell        | string          | Yes      | Cell address in A1 notation (e.g., 'A1', 'B5', 'AA100').                                   |

**Outputs**

| Field    | Type    | Description                |
| -------- | ------- | -------------------------- |
| Value    | string  | The cell value.            |
| Cell     | string  | The cell address.          |
| Is Empty | boolean | Whether the cell is empty. |
| Message  | string  | Status message.            |

#### Download Sheet

Download a Google Spreadsheet as an Excel, CSV, or PDF file

**Inputs**

| Field                | Type            | Required | Description                                                                                                      |
| -------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| Spreadsheet          | select (string) | Yes      | Select the Google Spreadsheet to download, or paste its ID. Options load from the selected connection.           |
| File Format          | select (string) | No       | Output file format (Excel, CSV, or PDF). Available values: Excel (.xlsx), CSV (.csv), PDF (.pdf). Default: xlsx. |
| File Name (Optional) | string          | No       | Custom file name (without extension). Defaults to spreadsheet name if empty.                                     |

**Outputs**

| Field     | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| File URL  | string | URL to download the generated file. |
| File Name | string | Name of the generated file.         |
| Message   | string | Status message about the operation. |

#### Append Row

Append a row to a Google Sheet

**Inputs**

| Field       | Type            | Required | Description                                                                                                   |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| Spreadsheet | select (string) | Yes      | Select the Google Spreadsheet to append a row to, or paste its ID. Options load from the selected connection. |
| Sheet       | select (string) | Yes      | Select the sheet/tab to append a row to. Options load from the selected connection.                           |
| Row Data    | object          | Yes      | Data for the new row. Keys must match column headers (case-insensitive).                                      |

**Outputs**

| Field         | Type    | Description                                    |
| ------------- | ------- | ---------------------------------------------- |
| Status        | string  | Status of the append operation.                |
| Row Number    | integer | The row number where data was appended.        |
| Updated Range | string  | The cell range that was updated (A1 notation). |
| Message       | string  | Description of what was appended.              |

#### Upsert Row

Insert or update a row based on a matching column value

**Inputs**

| Field        | Type            | Required | Description                                                                                                   |
| ------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| Spreadsheet  | select (string) | Yes      | Select the Google Spreadsheet to upsert a row in, or paste its ID. Options load from the selected connection. |
| Sheet        | select (string) | Yes      | Select the sheet/tab within the spreadsheet. Options load from the selected connection.                       |
| Match Column | string          | Yes      | Column to search for a matching value (e.g., Email, ID).                                                      |
| Match Value  | string          | Yes      | Value to find in the Match Column.                                                                            |
| Row Data     | object          | Yes      | Data for the row. On update, only these columns change. On insert, these become the new row.                  |

**Outputs**

| Field            | Type    | Description                                  |
| ---------------- | ------- | -------------------------------------------- |
| Status           | string  | Status of the operation.                     |
| Action Taken     | string  | Whether a row was inserted or updated.       |
| Row Number       | integer | The row number that was inserted or updated. |
| Columns Affected | array   | Column names that were written.              |
| Message          | string  | Description of what happened.                |

### Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

#### On Sheet Update

Trigger a workflow execution when any changes occur in a Google Sheet.

**Configuration**

| Field           | Type            | Required | Description                                                                                                                                                                                   |
| --------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Spreadsheet     | select (string) | Yes      | Select the Google Sheet to read from. Options load from the selected connection.                                                                                                              |
| Sheet           | select (string) | Yes      | Select the sheet/tab from the dropdown. Options load from the selected connection.                                                                                                            |
| Include Headers | boolean         | No       | Whether to treat the first row as column headers (true to use first row as headers, false otherwise). Default: true.                                                                          |
| Filter Range    | string          | Yes      | Range to filter the data by.                                                                                                                                                                  |
| Data Filter     | object          | Yes      | Filter to apply to the data. Supports single values or arrays for OR logic. Use '\*' as column name to search across all columns.{'\*': 'Published'} to search for 'Published' in any column. |

**Event inputs**

| Field                 | Type   | Required | Description                                                             |
| --------------------- | ------ | -------- | ----------------------------------------------------------------------- |
| Resource State        | string | Yes      | The state change that occurred (e.g., 'change', 'sync'). Default: None. |
| Changed Resource ID   | string | Yes      | The ID of the changed resource. Default: None.                          |
| Changed Resource Name | string | Yes      | The name of the changed resource. Default: NaN.                         |
| Changed Cells         | dict   | No       | The cells that changed based on the filter. Default: {}.                |

**Outputs**

| Field                 | Type        | Description                       |
| --------------------- | ----------- | --------------------------------- |
| Resource State        | string      | The type of change that occurred. |
| Changed Resource ID   | string      | The ID of the changed resource.   |
| Changed Resource Name | string      | The name of the changed resource. |
| Changed Cells         | dict\_array | The cells that changed.           |

### Important behavior

If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions.

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/google-sheets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
