# Google Sheets

Google Sheets is a cloud-based spreadsheet tool enabling real-time collaboration, data analysis, and integration with other Google Workspace apps

- **Category:** spreadsheets
- **Auth:** OAUTH2
- **Composio Managed App Available?** Yes
- **Tools:** 50
- **Triggers:** 16
- **Slug:** `GOOGLESHEETS`
- **Version:** 20260506_00

## Frequently Asked Questions

### How do I set up custom Google OAuth credentials for Google Sheets?

For a step-by-step guide on creating and configuring your own Google OAuth credentials with Composio, see [How to create OAuth2 credentials for Google Apps](https://composio.dev/auth/googleapps).

### Why am I seeing "App is blocked" when connecting Google Sheets?

The OAuth client is requesting scopes that Google hasn't verified for that client. This usually happens when you add extra scopes beyond the defaults.

Remove the additional scopes from your auth config, or create your own OAuth app and submit the scopes for verification. See [How to create OAuth2 credentials for Google Apps](https://composio.dev/auth/googleapps).

### Why am I getting "Google Sheets API has not been used in project" error?

When using custom OAuth credentials, the Google Sheets API must be enabled in the Google Cloud project that owns those credentials. Enable it in Google Cloud Console under APIs & Services, wait a few minutes, and retry.

### Why am I getting "Error 400: invalid_scope"?

The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/auth-configuration/programmatic-auth-configs).

### Why does the OAuth consent screen show "Composio" instead of my app?

By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).

### Why am I getting 401 errors on tool calls?

The user's access token is no longer valid. Common causes: the user revoked access, changed their password or 2FA, a Workspace admin policy changed, or Google's refresh token limit (~50 per account) was exceeded. Re-authenticating the user typically resolves this.

### Why am I getting "Quota Exhausted" or "rate limit exhausted"?

Google enforces per-minute and daily request quotas. If you're using Composio's default OAuth app, you share that quota with other users, which can cause limits to be hit faster. Use your own OAuth app credentials to get a dedicated quota, and add exponential backoff and retries to handle transient rate limits.

---

## Tools

### Add Sheet to Existing Spreadsheet

**Slug:** `GOOGLESHEETS_ADD_SHEET`

Adds a new sheet to a spreadsheet. Supports three sheet types: GRID, OBJECT, and DATA_SOURCE. SHEET TYPES: - GRID (default): Standard spreadsheet with rows/columns. Use properties to set dimensions, tab color, etc. - OBJECT: Sheet containing a chart. Requires objectSheetConfig with chartSpec (basicChart or pieChart). - DATA_SOURCE: Sheet connected to BigQuery. Requires dataSourceConfig with bigQuery spec and bigquery.readonly OAuth scope. OTHER NOTES: - Sheet names must be unique; use forceUnique=true to auto-append suffix (_2, _3) if name exists - For tab colors, use EITHER rgbColor OR themeColor, not both - Avoid 'index' when creating sheets in parallel (causes errors) - OBJECT sheets are created via addChart with position.newSheet=true - DATA_SOURCE sheets require bigquery.readonly OAuth scope Use cases: Add standard grid sheet, create chart on dedicated sheet, connect to BigQuery data source.

### Aggregate Column Data

**Slug:** `GOOGLESHEETS_AGGREGATE_COLUMN_DATA`

Searches for rows where a specific column matches a value and performs mathematical operations on data from another column.

### Append Dimension

**Slug:** `GOOGLESHEETS_APPEND_DIMENSION`

Tool to append new rows or columns to a sheet, increasing its size. Use when you need to add empty rows or columns to an existing sheet.

### Auto-Resize Rows or Columns

**Slug:** `GOOGLESHEETS_AUTO_RESIZE_DIMENSIONS`

Auto-fit column widths or row heights for a dimension range using batchUpdate.autoResizeDimensions. Use when you need to automatically adjust row heights or column widths to fit content after writing data.

### Batch Clear Values By Data Filter

**Slug:** `GOOGLESHEETS_BATCH_CLEAR_VALUES_BY_DATA_FILTER`

Clears one or more ranges of values from a spreadsheet using data filters. The caller must specify the spreadsheet ID and one or more DataFilters. Ranges matching any of the specified data filters will be cleared. Only values are cleared -- all other properties of the cell (such as formatting, data validation, etc..) are kept.

### Batch get spreadsheet

**Slug:** `GOOGLESHEETS_BATCH_GET`

Retrieves data from specified cell ranges in a Google Spreadsheet.

### Batch update spreadsheet (Deprecated)

**Slug:** `GOOGLESHEETS_BATCH_UPDATE`

DEPRECATED: Use GOOGLESHEETS_VALUES_UPDATE instead. Write values to ONE range in a Google Sheet, or append as new rows if no start cell is given. IMPORTANT - This tool does NOT accept the Google Sheets API's native batch format: - WRONG: {"data": [{"range": "...", "values": [[...]]}], ...} - CORRECT: {"sheet_name": "...", "values": [[...]], "first_cell_location": "...", ...} To update MULTIPLE ranges, make SEPARATE CALLS to this tool for each range. Features: - Auto-expands grid for large datasets (prevents range errors) - Set first_cell_location to write at a specific position (e.g., "A1", "B5") - Omit first_cell_location to append values as new rows at the end Requirements: Target sheet must exist and spreadsheet must contain at least one worksheet.

### Batch Update Values by Data Filter

**Slug:** `GOOGLESHEETS_BATCH_UPDATE_VALUES_BY_DATA_FILTER`

Tool to update values in ranges matching data filters. Use when you need to update specific data in a Google Sheet based on criteria rather than fixed cell ranges.

### Clear Basic Filter

**Slug:** `GOOGLESHEETS_CLEAR_BASIC_FILTER`

Tool to clear the basic filter from a sheet. Use when you need to remove an existing basic filter from a specific sheet within a Google Spreadsheet.

### Clear spreadsheet values

**Slug:** `GOOGLESHEETS_CLEAR_VALUES`

Clears cell content (preserving formatting and notes) from a specified A1 notation range in a Google Spreadsheet; the range must correspond to an existing sheet and cells.

### Create Chart in Google Sheets

**Slug:** `GOOGLESHEETS_CREATE_CHART`

Create a chart in a Google Sheets spreadsheet using the specified data range and chart type. Conditional requirements: - Provide either a simple chart via chart_type + data_range (basicChart), OR supply a full chart_spec supporting all chart types. Exactly one approach should be used. - When using chart_spec, set exactly one of the union fields (basicChart | pieChart | bubbleChart | candlestickChart | histogramChart | waterfallChart | treemapChart | orgChart | scorecardChart).

### Create a Google Sheet

**Slug:** `GOOGLESHEETS_CREATE_GOOGLE_SHEET1`

Creates a new Google Spreadsheet in Google Drive. If a title is provided, the spreadsheet will be created with that name. If no title is provided, Google will create a spreadsheet with a default name like 'Untitled spreadsheet'. Optionally create the spreadsheet in a specific folder by providing either: - folder_id: The Google Drive folder ID (preferred, unambiguous) - folder_name: The folder name (searches for exact match; if multiple folders match, returns choices) If neither folder_id nor folder_name is provided, the spreadsheet is created in the root Drive folder.

### Create spreadsheet column

**Slug:** `GOOGLESHEETS_CREATE_SPREADSHEET_COLUMN`

Creates a new column in a Google Spreadsheet. Specify the target sheet using sheet_id (numeric) or sheet_name (text). If neither is provided, defaults to the first sheet (sheet_id=0).

### Create spreadsheet row

**Slug:** `GOOGLESHEETS_CREATE_SPREADSHEET_ROW`

Inserts a new, empty row into a specified sheet of a Google Spreadsheet at a given index, optionally inheriting formatting from the row above.

### Delete Chart from Google Sheets

**Slug:** `GOOGLESHEETS_DELETE_CHART`

Delete an existing chart from a Google Sheets spreadsheet. Use this action when you need to remove a chart that is no longer needed or needs to be replaced. This action is irreversible — once a chart is deleted, it cannot be recovered. The chart data source (the cells containing the data) remains unchanged; only the chart visualization is removed.

### Delete Dimension (Rows/Columns)

**Slug:** `GOOGLESHEETS_DELETE_DIMENSION`

Tool to delete specified rows or columns from a sheet in a Google Spreadsheet. Use when you need to remove a range of rows or columns.

### Delete Sheet

**Slug:** `GOOGLESHEETS_DELETE_SHEET`

Tool to delete a sheet (worksheet) from a spreadsheet. Use when you need to remove a specific sheet from a Google Sheet document.

### Execute SQL on Spreadsheet

**Slug:** `GOOGLESHEETS_EXECUTE_SQL`

DEPRECATED: Use direct Google Sheets actions instead: - GOOGLESHEETS_VALUES_GET / GOOGLESHEETS_BATCH_GET for reads - GOOGLESHEETS_VALUES_UPDATE / GOOGLESHEETS_UPDATE_VALUES_BATCH / GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND for writes Execute SQL queries against Google Sheets tables. Supports SELECT, INSERT, UPDATE, DELETE operations and WITH clauses (CTEs) with familiar SQL syntax. Tables are automatically detected and mapped from the spreadsheet structure.

### Find and Replace in Spreadsheet

**Slug:** `GOOGLESHEETS_FIND_REPLACE`

Tool to find and replace text in a Google Spreadsheet. Use when you need to fix formula errors, update values, or perform bulk text replacements across cells. Common use cases: - Fix #ERROR! cells by replacing with empty string or correct formula - Update old values with new ones across multiple cells - Fix formula references or patterns - Clean up data formatting issues

### Find worksheet by title (Deprecated)

**Slug:** `GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE`

DEPRECATED: Use GetSpreadsheetInfo instead. Finds a worksheet by its exact, case-sensitive title within a Google Spreadsheet; returns a boolean indicating if found and the matched worksheet's metadata when found, or None when not found.

### Format cell

**Slug:** `GOOGLESHEETS_FORMAT_CELL`

Applies text and background cell formatting to a specified range in a Google Sheets worksheet.

### Batch Get Spreadsheet Values (Deprecated)

**Slug:** `GOOGLESHEETS_GET_BATCH_VALUES`

DEPRECATED: Use GOOGLESHEETS_BATCH_GET instead. Tool to return one or more ranges of values from a spreadsheet. Use when you need to retrieve data from multiple ranges in a single request.

### Get conditional format rules

**Slug:** `GOOGLESHEETS_GET_CONDITIONAL_FORMAT_RULES`

List conditional formatting rules for each sheet (or a selected sheet) in a normalized, easy-to-edit form. Use when you need to view, audit, or prepare to modify conditional format rules.

### Get Data Validation Rules

**Slug:** `GOOGLESHEETS_GET_DATA_VALIDATION_RULES`

Tool to extract data validation rules from a Google Sheets spreadsheet. Use when you need to understand dropdown lists, allowed values, custom formulas, or other validation constraints for cells.

### Get sheet names

**Slug:** `GOOGLESHEETS_GET_SHEET_NAMES`

Lists all worksheet names from a specified Google Spreadsheet (which must exist), useful for discovering sheets before further operations.

### Get Spreadsheet by Data Filter

**Slug:** `GOOGLESHEETS_GET_SPREADSHEET_BY_DATA_FILTER`

Returns the spreadsheet at the given ID, filtered by the specified data filters. Use this tool when you need to retrieve specific subsets of data from a Google Sheet based on criteria like A1 notation, developer metadata, or grid ranges. Important: This action is designed for filtered data retrieval. While it accepts empty filters and returns full metadata in that case, GOOGLESHEETS_GET_SPREADSHEET_INFO is the recommended action for unfiltered spreadsheet retrieval.

### Get spreadsheet info

**Slug:** `GOOGLESHEETS_GET_SPREADSHEET_INFO`

Retrieves metadata for a Google Spreadsheet using its ID. By default, returns essential information (ID, title, sheet properties) to avoid payload size issues. Use the fields parameter for comprehensive metadata or specific fields.

### Get Table Schema

**Slug:** `GOOGLESHEETS_GET_TABLE_SCHEMA`

DEPRECATED: Use GOOGLESHEETS_GET_SHEET_NAMES and GOOGLESHEETS_GET_SPREADSHEET_INFO for sheet structure metadata, and GOOGLESHEETS_VALUES_GET for direct range inspection. This action is used to get the schema of a table in a Google Spreadsheet, call this action to get the schema of a table in a spreadsheet BEFORE YOU QUERY THE TABLE. Analyze table structure and infer column names, types, and constraints. Uses statistical analysis of sample data to determine the most likely data type for each column. Call this action after calling the LIST_TABLES action to get the schema of a table in a spreadsheet.

### Insert Dimension in Google Sheet

**Slug:** `GOOGLESHEETS_INSERT_DIMENSION`

Tool to insert new rows or columns into a sheet at a specified location. Use when you need to add empty rows or columns within an existing Google Sheet.

### List Tables in Spreadsheet

**Slug:** `GOOGLESHEETS_LIST_TABLES`

DEPRECATED: Use GOOGLESHEETS_GET_SHEET_NAMES for tab discovery and GOOGLESHEETS_GET_SPREADSHEET_INFO for full sheet metadata. This action is used to list all tables in a Google Spreadsheet, call this action to get the list of tables in a spreadsheet. Discover all tables in a Google Spreadsheet by analyzing sheet structure and detecting data patterns. Uses heuristic analysis to find header rows, data boundaries, and table structures.

### Look up spreadsheet row

**Slug:** `GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW`

Finds the first row in a Google Spreadsheet where a cell's entire content exactly matches the query string, searching within a specified A1 notation range or the first sheet by default.

### Mutate conditional format rules

**Slug:** `GOOGLESHEETS_MUTATE_CONDITIONAL_FORMAT_RULES`

Add, update, delete, or reorder conditional format rules on a Google Sheet. Use when you need to create, modify, or remove conditional formatting without manually building batchUpdate requests. Supports four operations: ADD (create new rule), UPDATE (replace existing rule), DELETE (remove rule), MOVE (reorder rules by changing index).

### Query Spreadsheet Table

**Slug:** `GOOGLESHEETS_QUERY_TABLE`

DEPRECATED: Use GOOGLESHEETS_VALUES_GET / GOOGLESHEETS_BATCH_GET for table reads and GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW for row lookup/filter workflows. Execute SQL-like SELECT queries against Google Spreadsheet tables. Table names correspond to sheet/tab names visible at the bottom of the spreadsheet. Use GOOGLESHEETS_LIST_TABLES first to discover available table names if unknown. Supports WHERE conditions, ORDER BY, LIMIT clauses.

### Search Developer Metadata

**Slug:** `GOOGLESHEETS_SEARCH_DEVELOPER_METADATA`

Tool to search for developer metadata in a spreadsheet. Use when you need to find specific metadata entries based on filters.

### Search Spreadsheets

**Slug:** `GOOGLESHEETS_SEARCH_SPREADSHEETS`

Search for Google Spreadsheets using various filters including name, content, date ranges, and more.

### Set Basic Filter

**Slug:** `GOOGLESHEETS_SET_BASIC_FILTER`

Tool to set a basic filter on a sheet in a Google Spreadsheet. Use when you need to filter or sort data within a specific range on a sheet.

### Set Data Validation Rule

**Slug:** `GOOGLESHEETS_SET_DATA_VALIDATION_RULE`

Tool to set or clear data validation rules (including dropdowns) on a range in Google Sheets. Use when you need to apply dropdown lists, range-based dropdowns, or custom formula validation to cells.

### Create sheet from JSON

**Slug:** `GOOGLESHEETS_SHEET_FROM_JSON`

DEPRECATED: Use GOOGLESHEETS_CREATE_GOOGLE_SHEET1 + GOOGLESHEETS_UPDATE_VALUES_BATCH (or GOOGLESHEETS_VALUES_UPDATE / GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND) instead. Creates a new Google Spreadsheet and populates its first worksheet from `sheet_json`. When data is provided, the first item's keys establish the headers. An empty list creates an empty worksheet.

### Copy Sheet to Another Spreadsheet

**Slug:** `GOOGLESHEETS_SPREADSHEETS_SHEETS_COPY_TO`

Tool to copy a single sheet from a spreadsheet to another spreadsheet. Use when you need to duplicate a sheet into a different spreadsheet.

### Append Values to Spreadsheet

**Slug:** `GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND`

Tool to append values to a spreadsheet. Use when you need to add new data to the end of an existing table in a Google Sheet.

### Batch Clear Spreadsheet Values

**Slug:** `GOOGLESHEETS_SPREADSHEETS_VALUES_BATCH_CLEAR`

Tool to clear one or more ranges of values from a spreadsheet. Use when you need to remove data from specific cells or ranges while keeping formatting and other properties intact.

### Batch Get Spreadsheet Values by Data Filter

**Slug:** `GOOGLESHEETS_SPREADSHEETS_VALUES_BATCH_GET_BY_DATA_FILTER`

Tool to return one or more ranges of values from a spreadsheet that match the specified data filters. Use when you need to retrieve specific data sets based on filtering criteria rather than entire sheets or fixed ranges.

### Update Chart in Google Sheets

**Slug:** `GOOGLESHEETS_UPDATE_CHART`

Update the specification of an existing chart in a Google Sheets spreadsheet. Use this action when you need to modify an existing chart's properties such as its title, chart type, data ranges, colors, axes, or other visual settings. This action updates the chart's specification but does not change its position or size on the sheet.

### Update Dimension Properties (Hide/Unhide & Resize)

**Slug:** `GOOGLESHEETS_UPDATE_DIMENSION_PROPERTIES`

Tool to hide/unhide rows or columns and set row heights or column widths. Use when you need to change visibility or pixel sizing of dimensions in a Google Sheet.

### Update Sheet Properties

**Slug:** `GOOGLESHEETS_UPDATE_SHEET_PROPERTIES`

Tool to update properties of a sheet (worksheet) within a Google Spreadsheet, such as its title, index, visibility, tab color, or grid properties. Use this when you need to modify the metadata or appearance of a specific sheet.

### Update Spreadsheet Properties

**Slug:** `GOOGLESHEETS_UPDATE_SPREADSHEET_PROPERTIES`

Tool to update SPREADSHEET-LEVEL properties such as the spreadsheet's title, locale, time zone, or auto-recalculation settings. Use when you need to modify the overall configuration of a Google Spreadsheet. NOTE: To update individual SHEET properties (like renaming a specific sheet/tab), use GOOGLESHEETS_UPDATE_SHEET_PROPERTIES instead.

### Batch update spreadsheet values

**Slug:** `GOOGLESHEETS_UPDATE_VALUES_BATCH`

Tool to set values in one or more ranges of a spreadsheet. Use when you need to update multiple ranges in a single operation for better performance.

### Upsert Rows (Smart Update/Insert)

**Slug:** `GOOGLESHEETS_UPSERT_ROWS`

Upsert rows - update existing rows by key, append new ones. Automatically handles column mapping and partial updates. Use for: CRM syncs (match Lead ID), transaction imports (match Transaction ID), inventory updates (match SKU), calendar syncs (match Event ID). Features: - Auto-adds missing columns to sheet - Partial column updates (only update Phone + Status, preserve other columns) - Column order doesn't matter (auto-maps by header name) - Prevents duplicates by matching key column Example inputs: - Contact update: keyColumn='Email', headers=['Email','Phone','Status'], data=[['john@ex.com','555-0101','Active']] - Inventory sync: keyColumn='SKU', headers=['SKU','Stock','Price'], data=[['WIDGET-001',50,9.99],['GADGET-002',30,19.99]] - CRM lead update: keyColumn='Lead ID', headers=['Lead ID','Score','Status'], data=[['L-12345',85,'Hot']] - Partial update: keyColumn='Email', headers=['Email','Phone'] (only updates Phone, preserves Name/Address/etc)

### Get spreadsheet values

**Slug:** `GOOGLESHEETS_VALUES_GET`

Returns a range of values from a spreadsheet. Use when you need to read data from specific cells or ranges in a Google Sheet.

### Update spreadsheet values

**Slug:** `GOOGLESHEETS_VALUES_UPDATE`

Tool to set values in a range of a Google Spreadsheet. Use when you need to update or overwrite existing cell values in a specific range.


## Triggers

### Aggregate Metric Changed

**Slug:** `GOOGLESHEETS_AGGREGATE_METRIC_CHANGED_TRIGGER`

**Type:** poll

Triggers when an aggregate metric (SUM/COUNT/AVG/MIN/MAX) changes in a Google Sheets spreadsheet.
    This trigger monitors an aggregate calculation on a target column (optionally filtered by a search column/value)
    and fires when the calculated result changes.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `case_sensitive` | boolean | No | Whether the search should be case-sensitive when filtering by search_column and search_value. |
| `has_header_row` | boolean | No | Whether the first row contains column headers. If True, column names can be used for search_column and target_column. |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `operation` | string | Yes | The mathematical operation to perform on the target column values. Supported operations: sum, average, count, min, max, percentage. |
| `percentage_total` | number | No | For percentage operation, the total value to calculate percentage against. If not provided, uses sum of all values in target column. |
| `search_column` | string | No | The column to search in for filtering rows. Can be a letter (e.g., 'A', 'B') or column name from header row (e.g., 'Region', 'Department'). If not provided, all rows in the target column will be aggregated without filtering. |
| `search_value` | string | No | The exact value to search for in the search column. Case-sensitive by default. If not provided (or if search_column is not provided), all rows in the target column will be aggregated without filtering. |
| `sheet_name` | string | Yes | The name of the specific sheet within the spreadsheet to monitor. Matching is case-insensitive. If no exact match is found, partial matches will be attempted (e.g., 'overview' will match 'Overview 2025'). |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Sheets spreadsheet to monitor. This is the long alphanumeric string found in the spreadsheet URL between '/d/' and '/edit'. |
| `target_column` | string | Yes | The column to aggregate data from. Can be a letter (e.g., 'C', 'D') or column name from header row (e.g., 'Sales', 'Revenue'). |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `current_result` | number | Yes | The current aggregate metric value |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `event_type` | string | No | Type of event that occurred |
| `matching_rows_count` | integer | Yes | Number of rows that matched the search condition |
| `operation` | string | Yes | The aggregation operation performed |
| `previous_result` | number | Yes | The previous aggregate metric value |
| `processed_values_count` | integer | Yes | Number of values that were processed in the aggregation |
| `search_details` | object | Yes | Details of the search/filter used to select rows prior to aggregation |
| `sheet_name` | string | Yes | The sheet name |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |

### Cell Range Values Changed

**Slug:** `GOOGLESHEETS_CELL_RANGE_VALUES_CHANGED_TRIGGER`

**Type:** poll

Triggers when values in a specified A1 range change in Google Sheets.
    This trigger monitors a specific cell or range of cells and fires when any values change.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `range` | string | Yes | The A1 notation of the range to monitor for changes (can be a single cell or multi-cell range). If the sheet name contains spaces or special characters, wrap the sheet name in single quotes. |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor. This is the long alphanumeric string found in the spreadsheet URL between '/d/' and '/edit'. |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `current_values` | array | Yes | The current values in the range |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `event_type` | string | No | Type of event that occurred |
| `previous_values` | array | Yes | The previous values in the range |
| `range` | string | Yes | The A1 notation of the monitored range |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |

### Conditional Format Rule Changed

**Slug:** `GOOGLESHEETS_CONDITIONAL_FORMAT_RULE_CHANGED_TRIGGER`

**Type:** poll

Triggers when conditional formatting rules change in a Google Spreadsheet.
    Detects when rules are added, updated, or removed.
    Uses snapshot-based diffing to detect changes between polls.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `sheet_id` | integer | No | Optional filter: monitor only the sheet with this exact numeric sheetId. If not provided, monitors all sheets. If both sheet_title and sheet_id are provided, sheet_id takes precedence. |
| `sheet_title` | string | No | Optional filter: monitor only the sheet with this exact title. If not provided, monitors all sheets. |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor for conditional formatting rule changes |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `change_type` | string | Yes | Type of change: 'added', 'updated', or 'removed' |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `rules` | array | Yes | List of rules that changed |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |

### Data Validation Rule Changed

**Slug:** `GOOGLESHEETS_DATA_VALIDATION_RULE_CHANGED_TRIGGER`

**Type:** poll

Triggers when data validation rules change (added/updated/removed) in a Google Spreadsheet.
    Uses snapshot-based diffing to detect changes between polls.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `ranges` | array | No | Optional list of A1 ranges to monitor. If omitted, the entire sheet(s) will be monitored. |
| `sheet_id` | integer | No | Optional sheet ID to filter by. If omitted, all sheets will be monitored. |
| `sheet_title` | string | No | Optional sheet title to filter by. If omitted, all sheets will be monitored. |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor for data validation rule changes. |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `change_type` | string | Yes | Type of change: 'added', 'updated', or 'removed' |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `rules` | array | Yes | List of validation rules that changed |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |

### Developer Metadata Changed

**Slug:** `GOOGLESHEETS_DEVELOPER_METADATA_CHANGED_TRIGGER`

**Type:** poll

Triggers when developer metadata entries change (new/updated/removed) in a Google Spreadsheet.
    Uses snapshot-based diffing to detect changes between polls.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_filters` | array | No | The data filters describing the criteria used to determine which DeveloperMetadata entries to monitor. If not specified, monitors all developer metadata. |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor for developer metadata changes. |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `change_type` | string | Yes | Type of change: 'created', 'updated', or 'removed' |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `metadata_items` | array | Yes | List of metadata items that changed |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |

### Filtered Range Values Changed

**Slug:** `GOOGLESHEETS_FILTERED_RANGE_VALUES_CHANGED_TRIGGER`

**Type:** poll

Polling trigger that monitors Google Sheets filtered ranges for value changes.
    Uses snapshot-based diffing to detect when values matching a data filter change.
    Emits the matched values when changes are detected.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_filters` | array | Yes | List of data filters specifying which ranges to monitor for changes. Each filter can specify either 'a1Range' (e.g., 'Sheet1!A1:B10') or 'gridRange'. |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `major_dimension` | string ("ROWS" | "COLUMNS") | No | The major dimension that results should use. ROWS returns [[1,2],[3,4]], COLUMNS returns [[1,3],[2,4]] |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor |
| `value_render_option` | string ("FORMATTED_VALUE" | "UNFORMATTED_VALUE" | "FORMULA") | No | How values should be represented in the output |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `change_type` | string ("created" | "updated" | "deleted") | Yes | Type of change detected |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `new_values` | array | Yes | Current values in the range |
| `old_values` | array | No | Previous values in the range (None if new) |
| `range_identifier` | string | Yes | The A1 notation or identifier of the range that changed |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |

### New Rows in Google Sheet

**Slug:** `GOOGLESHEETS_NEW_ROWS_TRIGGER`

**Type:** poll

Simple polling trigger that monitors Google Sheets for new rows.
    Detects when new rows are added and returns the complete row data.
    Perfect for triggering any workflow based on new sheet entries.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `sheet_name` | string | No | The name of the specific sheet within the spreadsheet to monitor |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor |
| `start_row` | integer | No | The row number to start monitoring from (1-indexed, typically 2 to skip headers) |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `detected_at` | string | Yes | ISO timestamp when the row was detected |
| `row_data` | array | Yes | Complete row data as list of strings |
| `row_number` | integer | Yes | The row number in the sheet (1-indexed) |
| `sheet_name` | string | Yes | The sheet name |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |

### New Sheet Added in Google Spreadsheet

**Slug:** `GOOGLESHEETS_NEW_SHEET_ADDED_TRIGGER`

**Type:** poll

Polling trigger that detects when a new sheet is added to a Google Spreadsheet.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `detected_at` | string | Yes | ISO timestamp when the new sheet was detected |
| `sheet_name` | string | Yes | The name of the new sheet added |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |

### New Spreadsheet Created

**Slug:** `GOOGLESHEETS_NEW_SPREADSHEET_CREATED_TRIGGER`

**Type:** poll

Triggers when a new Google Spreadsheet is created.
    This trigger monitors Google Spreadsheets and fires when new spreadsheets are detected.
    Uses timestamp filtering to efficiently detect newly created spreadsheets.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `include_shared_drives` | boolean | No | Whether to include spreadsheets from shared drives you have access to. Defaults to True. |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `max_results` | integer | No | Maximum number of spreadsheets to check in each poll (1-1000) |
| `query` | string | No | Optional search query to filter spreadsheets. Can search by name (name contains 'Budget'), full text content (fullText contains 'sales'), or use complex queries with operators. Leave empty to monitor all spreadsheets. |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_type` | string | No | Type of event that occurred |
| `spreadsheet` | object | Yes | The newly created Google Spreadsheet |

### Spreadsheet Metadata Changed

**Slug:** `GOOGLESHEETS_SPREADSHEET_METADATA_CHANGED_TRIGGER`

**Type:** poll

Polling trigger that detects when a Google Spreadsheet's metadata changes.
    Uses snapshot-based diffing to detect any changes in spreadsheet properties,
    sheets, named ranges, developer metadata, data sources, etc.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor for metadata changes |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `changes` | array | Yes | List of metadata changes detected |
| `current_metadata` | object | Yes | Current metadata snapshot |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |
| `spreadsheet_url` | string | No | URL to view the spreadsheet |

### Spreadsheet Properties Changed

**Slug:** `GOOGLESHEETS_SPREADSHEET_PROPERTIES_CHANGED_TRIGGER`

**Type:** poll

Polling trigger that detects when a Google Spreadsheet's top-level properties change.
    Monitors properties such as title, locale, timeZone, and autoRecalc settings.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor for property changes |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `changed_properties` | array | Yes | List of properties that changed |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |
| `spreadsheet_url` | string | No | URL to view the spreadsheet |

### Spreadsheet Row Changed

**Slug:** `GOOGLESHEETS_SPREADSHEET_ROW_CHANGED_TRIGGER`

**Type:** poll

Triggers when a looked-up spreadsheet row changes.
    This trigger monitors a specific row (located by searching for a query value within a user-specified range)
    and fires when the row's values change, when the row appears, or when the row disappears.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `case_sensitive` | boolean | No | If `True`, the query string search is case-sensitive. |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `normalize_whitespace` | boolean | No | If `True`, strips leading and trailing whitespace from cell values before matching. This helps match cells like ' TOTAL ' or 'TOTAL ' when searching for 'TOTAL'. |
| `query` | string | Yes | Exact text value to find; matches the entire content of a cell in a row. |
| `range` | string | No | A1 notation range to search within. Supports cell ranges (e.g., 'Sheet1!A1:D5'), column-only ranges (e.g., 'Sheet1!A:Z'), and row-only ranges (e.g., 'Sheet1!1:1'). Defaults to the first sheet if omitted. IMPORTANT: Sheet names with spaces must be single-quoted (e.g., "'My Sheet'!A1:Z"). Bare sheet names without ranges (e.g., 'Sheet1') are not supported - always specify a range. |
| `spreadsheet_id` | string | Yes | Identifier of the Google Spreadsheet to monitor. |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `change_type` | string | Yes | Type of change: 'created' (row appeared), 'updated' (row values changed), or 'deleted' (row disappeared) |
| `current_row_data` | string | Yes | The current row data (empty dict if row is not found now) |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `event_type` | string | No | Type of event that occurred |
| `previous_row_data` | string | Yes | The previous row data (empty dict if row was not found before) |
| `query` | string | Yes | The query used to find the row |
| `range` | string | No | The A1 notation range that was searched |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |

### Spreadsheet Search Match

**Slug:** `GOOGLESHEETS_SPREADSHEET_SEARCH_MATCH_TRIGGER`

**Type:** poll

Triggers when a new spreadsheet appears that matches a saved search.
    This trigger uses snapshot-based diffing to detect when spreadsheets matching
    the search criteria are newly created or become visible to the user.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `created_after` | string | No | Return spreadsheets created after this date. Use RFC 3339 format like '2024-01-01T00:00:00Z'. |
| `include_shared_drives` | boolean | No | Whether to include spreadsheets from shared drives you have access to. Defaults to True. |
| `include_trashed` | boolean | No | Whether to include spreadsheets in trash. Defaults to False. |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `max_results` | integer | No | Maximum number of spreadsheets to check in each poll (1-100) |
| `modified_after` | string | No | Return spreadsheets modified after this date. Use RFC 3339 format like '2024-01-01T00:00:00Z'. |
| `order_by` | string | No | Order results by field. Common options: 'modifiedTime desc', 'modifiedTime asc', 'name', 'createdTime desc' |
| `query` | string | No | Search query to filter spreadsheets. Behavior depends on the 'search_type' parameter. For advanced searches, use Google Drive query syntax with fields like 'name contains', 'fullText contains', or boolean filters like 'sharedWithMe = true'. DO NOT use spreadsheet IDs as search terms. Leave empty to get all spreadsheets. |
| `search_type` | string ("name" | "content" | "both") | No | How to search: 'name' searches filenames only (prefix matching from the START of filenames), 'content' uses fullText search which searches file content, name, description, and metadata, 'both' explicitly searches both name OR content with an OR condition. |
| `shared_with_me` | boolean | No | Whether to return only spreadsheets shared with the current user. Defaults to False. |
| `starred_only` | boolean | No | Whether to return only starred spreadsheets. Defaults to False. |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_type` | string | No | Type of event that occurred |
| `spreadsheet` | object | Yes | The spreadsheet that matches the search criteria |

### Table Query Result Changed

**Slug:** `GOOGLESHEETS_TABLE_QUERY_RESULT_CHANGED_TRIGGER`

**Type:** poll

Triggers when the result set of a saved table query changes in Google Sheets.
    Detects rows added, removed, or updated in the query output.
    This trigger monitors the result of a SQL query against a Google Sheets table
    and fires when changes are detected.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `include_formulas` | boolean | No | Whether to return formula text instead of calculated values for formula columns |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to query. This is the long alphanumeric string found in the spreadsheet URL between '/d/' and '/edit'. |
| `sql` | string | Yes | SQL SELECT query to execute. The table name is the Google Sheets tab/sheet name (visible at the bottom of the spreadsheet). Supported: SELECT cols FROM table WHERE conditions ORDER BY col LIMIT n. Table names must be quoted with double quotes if they contain spaces or are numeric-only (e.g., SELECT * FROM "My Sheet" or SELECT * FROM "415"). |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `changes` | array | Yes | List of detected changes |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `event_type` | string | No | Type of event that occurred |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |
| `sql` | string | Yes | The SQL query that was executed |
| `total_rows_after` | integer | Yes | Total number of rows after the change |
| `total_rows_before` | integer | Yes | Total number of rows before the change |

### Table Schema Changed

**Slug:** `GOOGLESHEETS_TABLE_SCHEMA_CHANGED_TRIGGER`

**Type:** poll

Polling trigger that detects when a table's schema changes in Google Sheets.
    Monitors columns added/removed/renamed and inferred type/format changes.
    Uses snapshot-based diffing to compare schemas between polls.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `sample_size` | integer | No | Number of rows to sample for type inference |
| `sheet_name` | string | No | Sheet/tab name if table_name is ambiguous across multiple sheets |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor |
| `table_name` | string | Yes | Table name from LIST_TABLES response OR the visible Google Sheets tab name. Use 'auto' to monitor the largest/most prominent table. |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `change_summary` | string | Yes | Human-readable summary of the changes |
| `column_changes` | array | Yes | List of column changes detected |
| `current_column_count` | integer | Yes | Number of columns in current schema |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `previous_column_count` | integer | Yes | Number of columns in previous schema |
| `sheet_name` | string | Yes | Sheet name where table is located |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |
| `table_name` | string | Yes | Name of the table that changed |

### Worksheet Names Changed

**Slug:** `GOOGLESHEETS_WORKSHEET_NAMES_CHANGED_TRIGGER`

**Type:** poll

Triggers when the set of worksheet/tab names changes in a Google Spreadsheet.
    Detects when sheets are added, deleted, or renamed.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `spreadsheet_id` | string | Yes | The unique identifier of the Google Spreadsheet to monitor |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `change_type` | string | Yes | Type of change: 'added', 'deleted', or 'renamed' |
| `current_names` | array | Yes | Current list of all worksheet names after the change |
| `detected_at` | string | Yes | ISO timestamp when the change was detected |
| `previous_name` | string | No | Previous name if worksheet was renamed (only for renamed events) |
| `spreadsheet_id` | string | Yes | The spreadsheet ID |
| `worksheet_name` | string | Yes | The name of the worksheet that was added, deleted, or involved in the change |