Google Sheets Integration

Google Sheets integration for Apify

Google Sheets Integration synchronizes Google Sheets with Apify datasets and Actor workflows. Import spreadsheet rows into an Apify dataset, create worksheet tabs, or write JSON and dataset items back to a sheet with append, replace, upsert, delete, and clear operations.

The Actor is designed for scheduled data pipelines: connect a scraper's dataset to a reporting sheet, keep a content inventory current, or use Google Sheets as a simple operational data store. It supports no-credential reads of public sheets, service-account authentication for unattended automation, and Google API keys for public read-only API access.

Main features

• Read Google Sheets rows into the default Apify dataset.
• Create worksheet tabs, then append, replace, upsert, delete, or clear spreadsheet data.
• Upsert records using a unique business key such as email, id, or Dateiname.
• Export direct JSON rows or any Apify dataset.
• Filter reads and deletes using exact-match ALL or ANY criteria.
• Flatten nested objects and map source fields to report-friendly column headers.
• Batch large dataset exports and save a machine-readable run summary.

How to use Google Sheets Integration

1. Enable the Google Sheets API in a Google Cloud project.
2. For private sheets or writes, create a service account and download its JSON key.
3. Share each target spreadsheet with the service account client_email. Use Viewer access for reads and Editor access for writes.
4. For private sheets or writes, paste the complete JSON key into the secret serviceAccountKey field. Do not put the key in source code or a normal input field.
5. Choose an operation, spreadsheet ID or URL, and a sheet name or A1 range. Run the Actor manually, on a schedule, or after another Actor through an Apify integration.

The prefilled example reads Google's public sample sheet without credentials. For your own public read-only spreadsheet, provide a restricted googleApiKey when you need API access. API keys cannot write to Google Sheets.

Google Sheets operations

Operation	Use it when you need to
READ	Import spreadsheet rows into the default dataset.
CREATE_SHEET	Create a new worksheet tab, optionally populated with rows or a source dataset.
APPEND	Add new rows below an existing table.
REPLACE	Clear the selected range and write a new table.
UPSERT	Update matching rows and add new rows using upsertKey.
DELETE	Remove rows matching protected filters.
CLEAR	Empty a selected range without providing new rows.

READ uses the first worksheet when neither sheetName nor range is provided. For object rows, nested fields are flattened, for example profile.email. Use columnMapping to rename these fields for the sheet.

Input examples

Import a Google Sheet to an Apify dataset

{
  "operation": "READ",
  "spreadsheetId": "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit",
  "sheetName": "Leads",
  "firstRowHeaders": true,
  "filters": { "status": "active" },
  "filterMode": "ALL"
}

Upsert JSON data to Google Sheets

{
  "operation": "UPSERT",
  "spreadsheetId": "SPREADSHEET_ID",
  "sheetName": "Exports",
  "upsertKey": "email",
  "firstRowHeaders": true,
  "columnMapping": { "profile.email": "email" },
  "rows": [
    {
      "name": "Ada",
      "profile": { "email": "ada@example.com" },
      "status": "new"
    }
  ]
}

Create and populate a new worksheet tab

{
  "operation": "CREATE_SHEET",
  "spreadsheetId": "SPREADSHEET_ID",
  "sheetName": "Actor Test",
  "firstRowHeaders": true,
  "rows": [
    { "id": "write-test-001", "status": "created" }
  ]
}

Export another Actor's dataset

{
  "operation": "APPEND",
  "spreadsheetId": "SPREADSHEET_ID",
  "sheetName": "Scraper exports",
  "sourceDatasetId": "DATASET_ID_FROM_THE_SOURCE_ACTOR",
  "firstRowHeaders": true
}

Output

For READ, each spreadsheet row becomes one item in the default dataset. With firstRowHeaders enabled, the first sheet row becomes the object keys. Blank or duplicate headers are made unique.

Every successful operation writes an OUTPUT summary record to the default key-value store. It includes the operation, spreadsheet, range, and affected row count. READ summaries also include the number of populated cells read. This makes the Actor straightforward to chain through Apify integrations, the API, or MCP-enabled workflows.

Limits

READ operations allow up to 1,000,000 populated cells. For larger spreadsheets, select a narrower A1 range or split the import into multiple runs. This limit applies to the data returned by the selected range, not to the total capacity of the Google Sheets file.

Scheduling and integrations

Use Apify schedules to refresh a reporting sheet at a regular interval. To export a scraper's results automatically, create an Apify integration that runs Google Sheets Integration after the source Actor completes, then supply the source run's dataset ID as sourceDatasetId.

Pricing

Google Sheets Integration uses pay-per-event pricing. It charges once for each successful sheet operation: READ, APPEND, REPLACE, UPSERT, DELETE, or CLEAR. The current price is shown on the Actor's Pricing tab and includes platform usage. Invalid input, authentication failures, and failed Google API requests are not charged.

FAQ and troubleshooting

Why does Google return a permission error?

Share the spreadsheet with the service account's client_email. The service account needs Viewer access for READ and Editor access for write operations.

Why does UPSERT fail?

UPSERT requires firstRowHeaders: true, a non-empty upsertKey, and a value for that key in every input row. The target sheet must have a matching header column.

Why does DELETE require filters?

DELETE refuses to run without at least one exact-match filter to prevent accidental removal of all sheet rows.

Can I use Google OAuth instead of a service account?

This Actor currently uses service accounts for private sheets and API keys for public read-only sheets. Service accounts are better suited to scheduled, non-interactive Apify automations.

How do I get support?

Open an issue or contact the Actor publisher from the Actor's Apify Store page. Include the operation, non-sensitive input details, and the run log. Never include service-account JSON keys or API keys in support requests.