Book a demo

New or Updated Row

trigger.google_sheets_row
TriggerFiles & storageconnection requiredruns in-engine

Polls one tab on an interval and compares it with the last poll; one run per row.

Start a run for each new or updated row in a Google Sheet (polled).

Ask about Google SheetsAll Google Sheets nodesProvider API docs ↗

Connection

Required
Yes — the node will not save without one
Auth type
OAuth 2.0
Providers
Google Sheets
Secret shape
{"client_id", "client_secret", "refresh_token"}
Config it needs
token_uri
Resolved by
config.connection_id, else node.connection_id

Configuration

6 fields, 2 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

FieldTypeRequiredDefaultConstraintsExample
spreadsheet_id
The id from the sheet URL (between /d/ and /edit).
stringYes——1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
sheet_name
The tab to watch, exactly as it appears on its tab (e.g. Leads).
stringYes——Leads
mode
new_rows fires for rows appended below the last one seen. updated_rows also fires when an existing row's cells change, which costs a stored copy of each watched row.
stringNonew_rowsone of "new_rows", "updated_rows"—
key_column
Header name (or column letter) whose value identifies a row. Required for updated_rows; ignored for new_rows. Rows with an empty key are skipped, and a repeated key is watched once.
stringNo——Email
header_row
Which row holds the column names.
numberNo11–500—
poll_interval_sec
How often to check (30-86400 seconds).
numberNo6030–86400—

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "header_row": 1,
  "key_column": "Email",
  "mode": "new_rows",
  "poll_interval_sec": 60,
  "sheet_name": "Leads",
  "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
}

Output

One shape.

row

FieldTypeExample
spreadsheet_id
The spreadsheet the row lives in.
string—
sheet_name
The tab the row lives in.
string—
row_number
The sheet's own 1-based row number — address a write-back with it.
number42
row
The row as an object keyed by the header names.
object—
row_values
The row's raw cells, left to right — the honest reading when two header cells share a name or a column has no header.
array—
previous_row
The cells the previous poll recorded, keyed by the header in effect then. Null in new_rows mode and for a key seen for the first time.
object—
key
The key_column value that identifies this row. Empty in new_rows mode.
string—
change
'added' when the row was not there last poll, 'updated' when its cells changed.
stringadded
{
  "change": "added",
  "key": "",
  "previous_row": {},
  "row": {},
  "row_number": 42,
  "row_values": [],
  "sheet_name": "",
  "spreadsheet_id": ""
}

Notes

  • The sheet is never replayed: the first poll after publish only records its current state.
  • Runs are idempotent per (row, content) — a re-poll cannot start a second run.
  • new_rows: re-ordering the sheet does not re-fire the rows that moved, and if the rows the last poll ended on are all gone (the tab was cleared or refilled) the cursor resets and emits nothing rather than firing every row.
  • new_rows remembers the last 5,000 rows to tell a row that moved from a row that is new; a blank spacer row never starts a run.
  • updated_rows watches the first 5,000 rows (and at most 512 KiB of cell text); rows past that never fire.

Related Google Sheets nodes

Templates that use Google Sheets

Solutions with Google Sheets

See New or Updated Row run in a workflow.

In a technical demo we add the Google Sheets connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demoTalk to sales