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

Get data from a Google Sheet.

PREREQUISITE: Google account connection — the user must create it in the Floqer UI
(Connections page); an agent cannot. Without it the action fails the row with
a connection / authentication error. Confirm it exists before configuring.

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)

Last updated: 2026-04-28.