Skip to main content
Google Sheets is a cloud-based spreadsheet application that enables collaborative data management and analysis. Cargo’s native integration with Google Sheets allows you to read data from spreadsheets as part of data models, and write or update data in your sheets as part of automated workflows.

​
How to set up Google Sheets

Cargo supports two authentication modes for connecting to Google Sheets, each suited for different use cases:
Best for: Personal use, small to medium data volumes, quick setup - Uses your Google account credentials - Simple one-click authorization - Standard API rate limits (100 requests per 100 seconds per user) - Access to sheets you own or have been shared with

​
Authentication Mode 1: OAuth

OAuth is the simplest way to connect Google Sheets and is perfect for personal use or smaller workflows.

​
Step 1: Connect via OAuth

  1. In Cargo, navigate to the Google Sheets connector settings.
  2. Under Authentication, select OAuth.
  3. Click Connect and authorize Cargo to access your Google Sheets.
  4. Grant the required permissions when prompted.
Once connected, you can:
  • Set up a Google Sheets data model — Create data models from your spreadsheets to trigger Plays and power model search actions.
  • Use Google Sheets in workflows — Choose Google Sheets from the node catalog within a Play, Tool, or Agent.
OAuth connections have access to all sheets that your Google account has permission to view or edit. Make sure you’re using the correct Google account when connecting.

​
Authentication Mode 2: Service Account

Using a Service Account is the recommended way to connect Google Sheets if you need to process larger amounts of data without hitting standard API limits.

​
Prerequisite: Google Cloud Account

You must have a Google Cloud account to proceed.

​
Step 1: Generate Your Service Account Key

  1. Navigate to the Service Accounts > Keys section in your Google Cloud Console.
  2. Click the Add key button and select Create new key.
  3. In the popup window, select JSON as the “Key type”.
  4. Click Create.
    • Result: A file ending in .json will automatically download to your computer. This file contains the credentials Cargo needs.

​
Step 2: Connect to Cargo

  1. Open the .json file you just downloaded using a text editor (like Notepad on Windows or TextEdit on Mac) and copy the entire text.
  2. Go back to Cargo and open the Google Sheets connector settings.
  3. Under Authentication, select Service account (this enables the higher rate limit of 150 requests/min).
  4. Paste the text you copied into the Service account field.
  5. Click Save.

​
Step 3: Activate the Google Sheets API

For the connection to work, you must tell Google to allow this project to use Sheets.
  • Click this link: Enable Google Sheets API
  • Ensure the button says Enabled or click Enable if it is not already active.
  • You’re good to go.
When using a Service Account, you must share your Google Sheets with the service account email address (found in the JSON key file) for it to access your spreadsheets. The service account email typically looks like: [email protected]

​
Google Sheets actions

All Google Sheets actions support reading from and writing to any spreadsheet that your authentication method has access to.

​
Insert record

Insert a new row into a Google Sheet. Use cases
  • Lead capture – Create new leads from various sources and channels
  • Data logging – Add new entries to tracking sheets
  • Contact creation – Add new contacts from forms, events, or imports

​
Update record

Update an existing row in a Google Sheet. Use cases
  • Data enrichment – Keep spreadsheet information current and accurate
  • Status updates – Update record statuses and stages
  • Field updates – Modify specific cell values in existing rows

​
Upsert records

Upsert multiple rows into a Google Sheet (insert or update based on matching criteria). Use cases
  • Bulk data operations – Insert rows in bulk while avoiding duplicates
  • Data synchronization – Keep external systems synchronized with Google Sheets
  • Migration workflows – Import data from other systems while handling existing records
Upsert operations will match on the fields you specify. Ensure your matching criteria is unique to avoid unintended updates.

​
Google Sheets data models

Cargo allows you to create data models on top of your Google Sheets data that can be used to trigger Plays and power model search actions.

​
Creating Google Sheets data models

FieldDescription
NameChoose a descriptive name for your data model (required)
SlugSet a unique identifier that cannot be changed once created (required)
SpreadsheetSelect the Google Sheet you want to model
WorksheetSelect the specific worksheet within the spreadsheet
The first row of your selected range will be used as column headers. Make sure your sheet has a header row for best results. The fetchWorksheet extractor is used to retrieve data from your specified worksheet and range.

​
Rate limits

Authentication MethodRate Limit
OAuth100 requests per 100 seconds per user
Service Account150 requests per minute
Exceeding rate limits will result in errors. For high-volume workflows, use Service Account authentication to benefit from higher limits.

​
Security

  • All Google Sheets connections use Google’s secure authentication protocols
  • Service account keys are encrypted at rest in Cargo
  • OAuth tokens are securely stored and can be revoked at any time from your Google account settings
  • Cargo only requests the minimum permissions needed to read and write to your sheets