Google Sheets: Update range

Writes a list of rows into a block of cells, starting at the range you give.

• Kind: google-sheets.update_range
• Palette: Integrations, under Google Sheets
• Credential: a credential of kind bearer, named in credential
• Other Google Sheets actions: Read rows as objects, Append rows, Update or append a row by key, Read range, Clear range, Get spreadsheet details, Create spreadsheet, Add sheet

When to use

• Refreshing a report area: totals, a leaderboard, the latest status of each service.
• Writing a whole grid computed by an earlier step.

Writing the same values again leaves the same sheet, so a retried step is harmless. To add rows below a table, use append_rows; to change one record by its key, update_row_by_key.

Connection (with)

Field	Required	Description
spreadsheet_id	yes	The id in the spreadsheet’s address: docs.google.com/spreadsheets/d/<id>/edit. For example: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms.

Input (input)

Field	Type	Required	Description
range	string	yes	Where to write, in A1 notation. The values fill it from its top-left cell.
values	array of array	yes	Rows to write: a list of lists, e.g. [[“region”, “total”], [“north”, 12]].
value_input	string	no	Parse the values as if typed (formulas, dates), or store them as given. One of "USER_ENTERED", "RAW". Default "USER_ENTERED".
major_dimension	string	no	Whether each inner list is a row or a column. One of "ROWS", "COLUMNS". Default "ROWS".

Settings

Beside with and input in the node’s config.

Field	Type	Required	Description
credential	string	yes	Name of the project credential the action authenticates with.
fail_on_error_status	boolean	no	Treat any 4xx/5xx as a failure. On by default: an action either did its job or did not. Default true.
optional_when_untrusted	boolean	no	Run without the credential when the run is untrusted (a fork pull request), instead of failing. The credential is still withheld.
retry_on	array	no	Status codes that fail the node instead of returning, so its retry: policy applies (e.g. [429, 503]).

Output

The HTTP response. The reply is under body: nodes.<id>.output.body.<field>.

Field	Type	Description
status	integer	The HTTP status code.
headers	object	The response headers.
body	object	The response body, parsed as JSON when it is JSON.
body.spreadsheetId	string
body.updatedCells	integer
body.updatedColumns	integer
body.updatedRange	string	The range written, in A1 notation.
body.updatedRows	integer

How it runs

• On an agent with the connector capability. The managed environments have one, so this needs no agent of your own.
• One PUT request to sheets.googleapis.com.
• Any 4xx or 5xx fails the step, unless fail_on_error_status is false. retry: asks again after a 5xx, a 401, 408, 409, 423, 425 or 429, or a 4xx with Retry-After, and not after any other 4xx, which would get the same answer.
• 429 waited out and asked again with backoff, with no retry: on the step.

Example

version: hyperspool-graph/v1
nodes:
  - id: totals
    type: transform
    config:
      mode: all
      expr: |
        [["region", "orders"]].concat(
          Object.entries(input.by_region).map(([region, n]) => [region, n]))
  - id: write
    type: google-sheets.update_range
    config:
      credential: sheets
      with: { spreadsheet_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms }
      input:
        range: Summary!A1
        values: { $expr: "nodes.totals.output" }
edges:
  - { from: totals, to: write }

USER_ENTERED (the default) parses each cell as if typed, so =SUM(B2:B9) becomes a formula and 2026-09-27 a date; RAW stores them as given.

See Connectors for credentials and versions, and the node reference for every other node.