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

# Google Sheets Lookup

> Looks up rows in a Google Spreadsheet by matching column values, or reads a tab unfiltered.

Looks up rows in a Google Spreadsheet by matching values in one or more columns, and
returns either the complete matching rows or values from a specific column. Display
name **"Google Sheets Lookup"**. Off by default.

## Authentication and enablement

Requires a workspace Google Sheets OAuth integration. `access_token` is injected
(`x-variable-service: google_sheets`) and is never chosen by the model. Enable the
tool on the agent and bind the integration.

## Inputs

* `spreadsheet_id` (required): the spreadsheet ID from the URL.
* `sheet_name` (optional): defaults to the first sheet. Ignored when `gid` is set.
* `gid` (optional): the tab id (the number after `#gid=` in the spreadsheet URL).
  Takes precedence over `sheet_name` when both are set.
* `match_criteria` (required unless `raw` is true): column/value filters, AND'd
  across criteria, OR'd within a criterion's `values`. Supports `exact`, `prefix`,
  and `fuzzy` matching via `matching_strategy` / per-criterion `match_mode`.
* `return_column` (optional): extract one column's value per match into
  `found_values` instead of returning full rows.
* `raw` (optional, default false): skip `match_criteria` and header extraction
  entirely, and return every row of the tab unfiltered in `raw_rows` — an array of
  arrays, cell values in column order, row 0 not assumed to be a header row. Use
  this for sheets whose structure can't be expressed as column-value filters (e.g.
  grouping/header rows interleaved with data rows), typically feeding the raw grid
  into a `python_code_tool` that parses the structure itself.

## Output

Filtered mode: `columns` (headers), `found_rows` (matched rows keyed by header
name) or `found_values` (when `return_column` is set), `matched_values`,
`row_numbers`, `match_count`, `match_type`.

Raw mode (`raw: true`): `raw_rows` only — every row, unfiltered, in sheet order.
`columns`/`found_rows`/`found_values` are empty in this mode.

## Limits and side effects

* Read-only; no writes.
* Filtered mode does one uncapped `values.get` call per invocation.
* Raw mode uses a capped fetch (15 MB) and refuses cleanly on an oversized
  response, since it always returns the whole tab rather than a filtered subset —
  filtered mode is unaffected by this cap.

## Expected errors

* Missing/invalid Sheets integration token.
* Spreadsheet not found, or has no sheets.
* `gid` set but no tab with that id exists in the spreadsheet.
* `sheet_name` set but no tab matches it (exact or fuzzy).
* `match_criteria` empty when `raw` is not set.
* Referenced column not found, or out of range.