Docs / Strand / connectors/google-sheets

Google Sheets Connector

Read, write, and manage spreadsheet data in Google Sheets from your Strand workflows via the Sheets API v4.

Prerequisites

You need a Google Service Account with access to your spreadsheet:

Go to console.cloud.google.com
Create a new project (or select an existing one)
Enable the Google Sheets API: APIs & Services > Library > search "Google Sheets API" > Enable
Create a service account: IAM & Admin > Service Accounts > Create Service Account
Create a key: click the service account > Keys > Add Key > JSON > Download
Share your spreadsheet with the service account email (e.g., [email protected]) as an Editor

Tip: The service account email is in the JSON key file under client_email. You must share each spreadsheet with this email for the connector to access it.

Connector Setup

Create a Google Sheets connector from the Connectors page.

Configuration Fields

Field	Required	Description
Name	Yes	Friendly name (e.g., "Sales Tracker Sheet")
Service Account Key	Yes	Full JSON contents of the service account key file (encrypted at rest)
Spreadsheet ID	No	Default spreadsheet ID (can be overridden per node). Found in the URL: `docs.google.com/spreadsheets/d/{ID}/edit`
Timeout	No	Request timeout in seconds (default: 30)

Operations

Read Range

Read cell values from a spreadsheet range.

Field	Required	Description
Spreadsheet ID	No	Override the connector's default spreadsheet ID
Range	Yes	A1 notation range (e.g., `Sheet1!A1:D10`)
Value Render	No	How values are rendered: Formatted (default), Unformatted, or Formula

Example: Read a table

Range: Sheet1!A1:D100

Append Rows

Append rows to the end of a table in a spreadsheet.

Field	Required	Description
Spreadsheet ID	No	Override the connector's default spreadsheet ID
Range	Yes	Range indicating the table to append to (e.g., `Sheet1!A1`)
Values (JSON)	Yes	2D array of values as JSON. Supports Jinja templates.
Value Input	No	How input is interpreted: User Entered (default, parses formulas) or Raw

Example: Append a row from event data

Range: Sheet1!A1
Values:

json


[["{{ payload.name }}", "{{ payload.email }}", "{{ payload.date }}", "{{ payload.amount }}"]]

Example: Append multiple rows

json


[
  ["Alice", "[email protected]", "2025-01-15", 100],
  ["Bob", "[email protected]", "2025-01-16", 250]
]

Update Range

Update specific cells in a spreadsheet.

Field	Required	Description
Spreadsheet ID	No	Override the connector's default spreadsheet ID
Range	Yes	A1 notation range to update (e.g., `Sheet1!A1:B2`)
Values (JSON)	Yes	2D array of values as JSON
Value Input	No	How input is interpreted: User Entered (default) or Raw

Clear Range

Clear all values from a range (formatting is preserved).

Field	Required	Description
Spreadsheet ID	No	Override the connector's default spreadsheet ID
Range	Yes	A1 notation range to clear (e.g., `Sheet1!A2:D100`)

Get Spreadsheet Info

Get spreadsheet metadata including sheet names and dimensions.

Field	Required	Description
Spreadsheet ID	No	Override the connector's default spreadsheet ID

Output

Read Range Output

json


{
  "success": true,
  "status": "completed",
  "data": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
    "range": "Sheet1!A1:D3",
    "values": [
      ["Name", "Email", "Date", "Amount"],
      ["Alice", "[email protected]", "2025-01-15", "100"],
      ["Bob", "[email protected]", "2025-01-16", "250"]
    ],
    "row_count": 3
  },
  "service": "google_sheets",
  "operation": "read_range"
}

Key fields for subsequent nodes:

{{ steps.node_id.output_payload.data.values }}: 2D array of cell values
{{ steps.node_id.output_payload.data.row_count }}: Number of rows returned

Append Rows Output

json


{
  "success": true,
  "status": "completed",
  "data": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
    "updated_range": "Sheet1!A4:D4",
    "updated_rows": 1,
    "updated_cells": 4
  },
  "service": "google_sheets",
  "operation": "append_rows"
}

Get Spreadsheet Info Output

json


{
  "success": true,
  "status": "completed",
  "data": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
    "title": "Sales Tracker",
    "sheets": [
      {"sheet_id": 0, "title": "Sheet1", "row_count": 1000, "column_count": 26},
      {"sheet_id": 123, "title": "Summary", "row_count": 100, "column_count": 10}
    ],
    "sheet_count": 2
  },
  "service": "google_sheets",
  "operation": "get_spreadsheet"
}

Errors

Error	Meaning
Google authentication failed	Service account key is invalid or expired.
Access denied	Spreadsheet not shared with the service account email.
Spreadsheet or range not found	Check the spreadsheet ID and range notation.
PyJWT library is required	A platform-side dependency issue. If you see this, contact support.

Example Workflow

Create Connector with your service account key and default spreadsheet ID
Read Range to get current data: Sheet1!A1:D100
Logic node to check if a condition is met
Append Rows to log new data:

Range: Sheet1!A1
Values: [["{{ payload.name }}", "{{ payload.value }}", "{{ payload.timestamp }}"]]

Limitations

Formatting: Only cell values can be read/written. Cell formatting, charts, and conditional formatting are not supported via this connector.
Large spreadsheets: Reading very large ranges may timeout. Use specific ranges instead of full-sheet reads.
Rate limits: Google Sheets API has a quota of 300 requests per minute per project. Use delays between rapid operations.
File creation: Creating new spreadsheets is not supported. Create them manually and share with the service account.

← Back to Strand docs