Google Sheets Sync: Export & Import

Send any Apify dataset to Google Sheets, keep a sheet up to date with upserts, or import a sheet into a dataset. It authenticates with a Google service account, so scheduled runs and integrations keep working without ever logging in again.

• ➕ Append new rows below existing data
• 🔄 Replace the sheet content with the latest results
• 🔑 Upsert by key (for example url or id): update rows that already exist, add the new ones
• 📥 Import a sheet or range into an Apify dataset (optionally rebuilding nested objects)
• 🧩 Nested data flattened into columns like Apify's CSV export (address/city, images/0), or dot notation, or JSON
• 🛡️ Formulas in your own columns are never overwritten; values are stored exactly as they are (no accidental formulas)
• ⚡ Works as an integration: attach it to any scraper and every finished run lands in your sheet
• 🧭 Clear error messages: it tells you exactly which e-mail to share the sheet with, or which API to enable

Why a service account?

Tools that use "Sign in with Google" store a token that expires or gets revoked, so scheduled runs start failing. A service account is a robot Google account with a key that doesn't expire. You share a spreadsheet with it once, like you would with a colleague, and it can only touch the spreadsheets you shared.

Setup in 5 minutes

1. Open Google Cloud Console and create a project (any name). No billing is needed: the Google Sheets API is free. If the console offers a free trial, you can skip it.
2. Go to APIs & Services → Library, search for Google Sheets API and click Enable.
3. Go to IAM & Admin → Service Accounts → Create service account. Give it a name; no roles are needed.
4. Open the new account, go to Keys → Add key → Create new key → JSON. A .json file downloads.
5. In your spreadsheet click Share and add the service account's e-mail (...@...iam.gserviceaccount.com, also in the file as client_email) as Editor.
6. In this Actor, paste the spreadsheet URL and the whole content of the JSON file into Service account key. The key is stored encrypted.

How to use it

As an integration (recommended)

1. Open the scraper whose results you want in Sheets and go to its Integrations tab.
2. Click Add integration, choose Google Sheets Sync and fill in the spreadsheet URL, the key and the mode.
3. Make sure Dataset to export contains {{resource.defaultDatasetId}} (it is prefilled when you add the integration). Each finished run of the scraper is then exported automatically. The Actor runs with limited permissions, so it can only read the dataset passed in this field.

Run it directly

Pick a dataset in Dataset to export (or paste JSON into Rows), choose a mode and click Start.

Via the API

curl -X POST "https://api.apify.com/v2/acts/datadock-labs~google-sheets-sync/runs?waitForFinish=120" \
  -H "Authorization: Bearer $APIFY_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "mode": "upsert",
    "spreadsheetId": "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit",
    "sheetName": "Products",
    "keyColumns": ["url"],
    "rows": [{ "url": "https://shop.example/a", "price": 19.9 }],
    "serviceAccountKey": "{ ...contents of the JSON key file... }"
  }'

Modes

Mode	What happens
append	Rows are added below the existing data. New fields become new columns on the right (unless you turn Add new columns off).
replace	The tab is cleared, then the header and all rows are written.
upsert	Rows whose key columns match an existing row update only the columns present in the data; other rows are added at the bottom. If the input contains the same key twice, the last one wins.
import	The tab (or Range to import) is read; the first row becomes the field names and every other non-empty row becomes a dataset item.

Input

Field	Description
mode	append (default), replace, upsert or import
spreadsheetId	Spreadsheet URL or ID. A URL with #gid= selects that tab.
sheetName	Tab name. Missing tabs are created. Empty = first tab.
serviceAccountKey	Full JSON key of the service account (secret)
keyColumns	Key column(s) for upsert, for example ["url"]
datasetId	Dataset to export. Empty in integrations: the triggering run's dataset is used.
rows	JSON array of objects to write instead of a dataset
columns / excludeColumns	Choose, order or drop columns. A parent name (address) matches its nested fields (address/city).
flattenMode	apify (default: address/city, tags/0), dot (address.city, lists as JSON) or none (nested values as JSON)
addNewColumns	Add unknown fields as new columns (default true)
parseValues	Let Google parse dates, numbers and formulas from text (default false: values are stored as they are)
formatHeader	Bold and freeze a newly written header row (default true)
maxItems	Export at most this many items
importRange, importFormatted, unflatten	Import options
googleAccessToken	Advanced: an OAuth access token instead of a service account

Output

After an export, the run's key-value store contains an OUTPUT record:

{
    "mode": "upsert",
    "sheet": "Products",
    "sheetCreated": false,
    "spreadsheetUrl": "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0",
    "rowsAppended": 12,
    "rowsUpdated": 230,
    "columnsAdded": ["discount"],
    "truncatedCells": 0,
    "stoppedByCostLimit": false,
    "warnings": []
}

In import mode the rows are stored in the run's dataset, ready to download as JSON, CSV or Excel or to pass to another Actor.

Pricing

Pay per event, no subscription:

Event	Price
Sync run (charged once per run that writes or imports at least one row)	$0.002
Row written or imported	$0.00001 ($0.01 per 1,000 rows)

Example: exporting 1,000 rows costs $0.012. Runs that fail before writing anything are not charged. You can set a maximum cost per run; the Actor stops cleanly when it is reached.

FAQ

Do I need Google Cloud billing? No. The Google Sheets API is free and service accounts don't need a billing account.

Is my key safe? The key is stored as an encrypted secret input and is only used to call the Google Sheets API with the spreadsheets scope. The service account can only open spreadsheets that you explicitly share with it, and you can delete the key in Google Cloud at any time.

Will it overwrite my formulas? No. Upserts only write the columns that exist in your data, and values are written as plain values unless you turn on Parse values. Text like =SUM(...) coming from scraped data stays text.

Why can't it create a new spreadsheet? Files created by a service account belong to the robot account and would be invisible to you. Create an empty spreadsheet, share it, and the Actor creates the tabs it needs.

What are the limits? Google allows 10 million cells per spreadsheet and 50,000 characters per cell (longer text is truncated with a warning). Write-quota errors from Google are retried automatically with back-off.

I get "no permission". Share the spreadsheet with the service account's e-mail as Editor. The error message shows the exact address.

I get "Google Sheets API is turned off". Enable the Google Sheets API in the same Google Cloud project as your service account. The error message contains the direct link.

More from DataDock Labs

• Website Screenshot & PDF API: full-page screenshots and PDFs of any website. Pair it with this Actor to keep a visual log of pages in a sheet.

Support

Something not working? Open an issue on the Issues tab with your input (never paste your key). You can also email datadocklabs@gmail.com or see the support page. More tools from DataDock Labs: datadock-labs.github.io. If this Actor saves you time, a short review on its Store page helps other people find it. Thank you!

Changelog

• 0.1 (November 2026): first release. Append, replace, upsert by key, import, flattening modes, integration support, service account and access token authentication.