Google Sheets Import & Export – Sheets Sync Pro

Export any Apify dataset or JSON to a Google Sheet (append, replace, or upsert), or import a sheet into a dataset. Private sheets use the official Google Sheets API v4 with your own service account (recommended) or an OAuth access token. There is no OAuth pop-up and no shared token store.

A sheet shared as anyone with the link can be imported with no credentials (import-public). That mode is the default, so the Apify Store health run succeeds without secrets.

Why another Sheets Actor? Incumbent failure analysis

The store leader lukaskrivka/google-sheets has 812 users/30d and 4.81★, but only 49% of runs succeeded in the last 30 days: 40,940 succeeded vs 42,605 failed out of 83,622 runs (public store API, 2026-10-13). From its public README and issue titles:

Incumbent failure mode (evidence)	How this Actor handles it
OAuth connect breaks: issues "Cannot authorize Google Drive", "Doesn't allow to Auth in Google", "Getting spreadsheet metadata failed with error invalid_request"; a deprecated tokens store	Stateless auth: a service-account JWT signed in code, or a raw OAuth token. No token store, no browser consent step. Works in schedules, API calls and MCP/agent runs (issue: "unable to run this actor through Claude MCP")
README: exceeding 60 reads/updates per minute makes "the actor run fail, and no data will be imported"	Retries every call on 429/5xx/network errors with exponential backoff and jitter, and honours Retry-After (default 6 retries)
"You reached the max limit of 5000000 cells" (an outdated limit; Google's is now 10M), discovered mid-run	The cell budget is checked before writing and nothing is written if it would overflow. columnsMapping + onlyMappedColumns shrink exports
Generic "The main function of the Actor threw an exception" / "Actor keeps throwing exception"	Every error says what failed and what to do: the exact client_email to share the sheet with, enabling the Sheets API, the right ID, a bad range or tab (lists existing tabs), a mangled private key (lost \n line breaks), an expired token
Rewrites the whole sheet on every run; locale-dependent parsing ("1,1" vs "1.1")	Append writes only new rows. Replace writes first, then clears leftover rows, with a backup in the KV record BACKUP. valueInputOption=RAW by default, so values are stored exactly
Silent "success" when nothing happened	Fails loudly on 0 rows (empty dataset, empty sheet, or every row a duplicate). allowEmpty=true opts out for incremental schedules
Wrong tab name ("Importing to a Different Sheet Name")	sheetName is explicit, and missing tabs are created on export

Modes

• import-public (default, v0.4): reads a spreadsheet shared as Anyone with the link. It does not call the Sheets API and ignores serviceAccountJson / oauthAccessToken. The download URL is https://docs.google.com/spreadsheets/d/{spreadsheetId}/export?format=csv&gid={gid}. gid is the tab id (usually 0 for the first tab); sheetName is not used. The first row is headers. columnsMapping, dedupeBy, limit, and allowEmpty work as in import. The default spreadsheet is Google's public Class Data sample (1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms).
• export-append: adds rows below existing data. It keeps the existing column order and appends new columns at the end. dedupeBy skips rows whose key already exists in the sheet.
• export-replace: overwrites the tab. The old content is backed up first.
• export-upsert (v0.2): updates rows in place by upsertKey (one or more columns). A row whose key matches a sheet row overwrites that row. Fields missing from the input keep their current sheet value. Unmatched rows are appended, and new columns are added at the end. Only changed rows are written, and unchanged rows are counted, not rewritten.
• import: reads a private sheetName[!range] through the Sheets API and treats the first row as headers. columnsMapping renames headers; dedupeBy and limit are supported. Output goes to the dataset. Requires a service account or OAuth token, and the sheet must be shared with that identity.

v0.4 keeps the v0.2 export behavior and the v0.3 dedupeBy coercion. The default mode is now import-public so a run that uses only schema defaults and prefills does not need Google credentials. Pass mode explicitly for export or private import.

dedupeBy is a string or an array of column names. ["id","city"] and the comma-separated string "id,city" select the same columns. Empty, missing, or whitespace-only values skip deduplication.

Per-row error reporting (v0.2): export modes return rowErrors[] in the OUTPUT record and push one type: "row-error" dataset item per problem: inputRow, key, column, severity (error = row skipped, warning = written with changes such as truncation) and error. Upsert flags rows with a missing key or a duplicate key in the input. The run still succeeds when other rows were written.

v0.2 is backward-compatible: existing inputs and modes behave as before, and the new output fields are additive.

v0.3 keeps that compatibility and accepts dedupeBy as a string or an array inside the core runner (the same comma-separated coercion main.js already applies).

Nested objects are flattened with / (geo/lat, tags/0). Cells longer than 50,000 characters are truncated with a marker instead of failing the batch.

Setup (2 minutes, private sheets only)

Skip this for import-public. The default run does not need a Google account.

1. Google Cloud Console: create or choose a project, then enable Google Sheets API.
2. IAM → Service accounts → Create → Keys → Add key → JSON. Paste the file into serviceAccountJson (it is stored as a secret).
3. Share your spreadsheet with the service account's client_email (Editor for export, Viewer for import).

Pricing (pay per event)

Event	Price
run-started: custom flat event, charged once per run after a successful import or export. A failed run is not billed (not Apify's memory-scaled apify-actor-start)	$0.005
row-batch: per started block of 1,000 rows written or read	$0.002

When publishing, configure run-started as a custom event. Do not enable the synthetic start event, which is priced per GB of memory. See PRICING.md.

---

Built and maintained by MasterInvictus.