ACTION_ID: google_sheets_lookup_rows
NAME: Google Sheets: Get Data
CATEGORY: sheets
CREDITS: 0

Get data from a Google Sheet.

================================================================================
PREREQUISITE — USER ACTION REQUIRED
================================================================================

This action only works if the user has connected their Google account
in Floqer. The connection cannot be made via the API or by an AI agent.

The user must do this themselves before this action will run:
  1. Sign in to Floqer at https://app.floqer.com
  2. Open the Connections page from the sidebar
  3. Click Google Sheets and complete the OAuth flow

If the user has not connected Google Sheets, this action will fail with a
connection / authentication error. Before configuring or running this
action, confirm with the user that the Google Sheets connection exists.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

spreadsheets (spreadsheetsDropdown, required)
  Spreadsheets. Select Google Spreadsheet. Values from
  google_spreadsheets.

sheet_name (inSheetDropdown, required)
  Sheet Name. Select Sheet. Values from google_spreadsheet_sheets.

search_criteria (criteriaArray, optional)
  Search Criteria. Build search criteria with field, operator and
  value. Values from sheetColumns. Operators: EQUALS, CONTAINS,
  LESS_THAN, GREATER_THAN.

limit_rows (number, optional)
  Limit Rows. Maximum number of rows to return. Placeholder: "100".

================================================================================
2. OUTPUTS
================================================================================

values (array) — Values. Values from the spreadsheet.
major_dimension (string) — Major Dimension. Major dimension of the
  values.
range (string) — Range. Range that was retrieved.
total_rows (number) — Total Rows. Total number of rows.
returned_rows (number) — Returned Rows. Number of rows returned.

================================================================================
3. HOW TO CONFIGURE
================================================================================

Resolve dropdowns via Get Action Field Options:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/spreadsheets
       (body: {})
  POST .../options/sheet_name
       (body: { "context": { "spreadsheets": "<spreadsheet_id>" } })
  POST .../options/search_criteria
       (body: { "context": { "spreadsheets": "<spreadsheet_id>",
                             "sheet_name": "Sheet1" } })
       → column headers on the chosen sheet (use as filter `field`s).

Configure Action body:

{
  "inputs": {
    "spreadsheets": "<spreadsheet_id>",
    "sheet_name": "Leads",
    "search_criteria": [
      { "field": "Email", "operator": "EQUALS", "value": "{{input.email}}" }
    ],
    "limit_rows": 100
  }
}

Field-by-field:
  - spreadsheets      Google spreadsheet ID.
  - sheet_name        Tab name on the spreadsheet.
  - search_criteria   Optional filter list. Each item is
                      `{field, operator, value}`. Operators: `EQUALS`,
                      `CONTAINS`, `LESS_THAN`, `GREATER_THAN`. Multiple
                      criteria are AND-ed.
  - limit_rows        Max rows returned. Default unset (returns all
                      matching rows).

================================================================================
4. KEY NOTES
================================================================================

- Returns the matched rows in `values` as a 2D array (rows × columns)
  matching the sheet's left-to-right column order. To work row-by-row
  downstream, follow with `raw_to_structured_array` and then
  `push_data_to_sheet` to fan out.
- The `total_rows` output is the count of rows in the SHEET (before
  filter); `returned_rows` is what came back after filtering / limit.
- Filtering is server-side at the Google Sheets API — returns only
  rows that match all `search_criteria`.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern: google_sheets_lookup_rows -> downstream actions iterate the
returned rows.

================================================================================
6. WHEN TO USE
================================================================================

Use google_sheets_lookup_rows to read filtered rows from a Google Sheet.

================================================================================
7. WHEN NOT TO USE
================================================================================

Need to write to the sheet
  -> google_sheet_add_data or google_sheet_upsert_row
     (https://floqer.com/docs/action-detail/google_sheet_add_data.txt or
      https://floqer.com/docs/action-detail/google_sheet_upsert_row.txt)

================================================================================

This file is maintained manually. Last updated: 2026-04-28.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt