Google Sheets Import & Export — Service Account Auth (Never Expires)

Send Apify data to Google Sheets — or read a sheet back into a dataset — with a connection that never expires and never needs re-authorizing.

If you've ever had a scheduled export silently die with "authorization expired", "invalid_grant", or "token has been revoked", this actor is the fix. OAuth-based Sheets integrations depend on a personal login token that Google expires or revokes — and every time it does, your pipeline breaks until a human clicks "re-authorize". This actor uses a Google service account instead: a robot identity with its own key. Keys don't expire, there's no consent screen, and a scheduled run in six months behaves exactly like the one you ran today. Free to use.

What it does

Mode	What happens
append	Adds rows below the existing data. Headers stay stable; genuinely new fields become new columns on the right.
replace	Clears the sheet (tab), then writes a fresh header row + all rows.
read	Reads the sheet (first row = headers) into the run's dataset — export a Sheet as JSON/CSV/Excel or feed it to another actor.

Plus the details that make it dependable:

• Never fails on rate limits — writes are batched (up to 5,000 rows per request), calls are spaced under Google's ~60-requests/minute quota, and any 429 is retried with exponential backoff. The actor slows down; it doesn't die.
• 10-million-cell cap pre-check — if the write would exceed Google Sheets' hard limit, you get one clear error before anything is written. No half-written sheets.
• Nested data flattened — {"contact": {"email": "a@b.com"}} becomes a contact.email column; arrays are stored as JSON.
• Stable columns across appends — the existing header row is respected; new keys extend it on the right, so your formulas and pivot ranges keep working.
• Paste the URL, not just the ID — spreadsheetId accepts the full browser URL.
• Missing tab? Created automatically in write modes.
• Integration-friendly — attach it to any actor as an integration and it auto-detects the triggering run's dataset; or pass a datasetId / inline rawData yourself.
• Clear errors — every failure tells you exactly what to do (which email to share the sheet with, which API to enable, what was wrong with the key).

One-time setup (~5 minutes, never again)

You'll create a service account — think of it as a robot colleague with its own email address — and share your spreadsheet with it.

1. Create (or pick) a Google Cloud project — go to console.cloud.google.com, sign in, and create a project (any name, e.g. sheets-automation). Free; no billing needed.
2. Enable the Google Sheets API — in that project, open APIs & Services → Library and click Enable.
3. Create a service account — IAM & Admin → Service Accounts → Create service account. Name it anything (e.g. apify-sheets). No roles needed — click through and Done.
4. Download its JSON key — click the new service account → Keys tab → Add key → Create new key → JSON. A .json file downloads. This file is the credential — treat it like a password.
5. Share your spreadsheet with the robot — open the .json file and copy the client_email value (looks like apify-sheets@your-project.iam.gserviceaccount.com). In Google Sheets, click Share, paste that email, give it Editor, untick "Notify", and share — exactly like sharing with a colleague.
6. Paste the key into this actor — open the .json file in any text editor, copy everything, and paste it into the Service Account JSON Key field. It's stored encrypted by Apify.

That's it — forever. No consent screens, no token refresh, no re-authorization. To revoke access later, just un-share the spreadsheet or delete the key in Google Cloud.

Inputs

Field	Notes
serviceAccountKey	Full contents of the service-account .json key (stored encrypted).
mode	append (default) / replace / read.
spreadsheetId	Bare ID or full https://docs.google.com/spreadsheets/d/… URL.
sheetName	Tab name. Defaults to the first tab; auto-created in write modes.
datasetId	Apify dataset to write. Optional when running as an integration — the triggering run's dataset is detected automatically.
rawData	Alternative inline data: JSON array of objects.
range	Optional A1 range for read (e.g. A1:D50).

Output

Write modes push a summary record to the dataset (and to the OUTPUT key-value record):

{
  "mode": "append",
  "rowsWritten": 1250,
  "columns": ["company", "contact.name", "contact.email", "score"],
  "columnCount": 4,
  "sheetName": "Leads",
  "spreadsheetUrl": "https://docs.google.com/spreadsheets/d/…/edit",
  "durationSecs": 8.4
}

Read mode pushes each sheet row as a dataset item, keyed by the header row.

Typical usage

• Actor → Sheet, on every run: add this actor as an integration on any scraper with mode: append — new results land in your sheet automatically, and the connection never rots.
• Nightly refresh: mode: replace on a schedule keeps a sheet as an always-current mirror of your latest dataset.
• Sheet as input: mode: read turns a spreadsheet your team edits into a dataset any actor can consume.

Why service accounts beat OAuth here

	OAuth (sign in with Google)	Service account (this actor)
Token lifetime	Expires; revoked by password changes, security events, 6-month inactivity	Key never expires
Scheduled runs	Break until someone re-authorizes	Deterministic, forever
Access scope	Your entire Drive	Only spreadsheets you explicitly share
Revoking	Hunt through Google security settings	Un-share the sheet, or delete the key

---

Need something more custom? Different targets (Excel/BigQuery), formatting, dedup/upsert logic, multi-tab writes, or a fully managed data pipeline — message me via my Apify profile and I'll build it.