# Google Sheets Import & Export — Fast, Reliable Sync (`surefetch/google-sheets`) Actor

Import Apify datasets, JSON or CSV into Google Sheets and export sheets back to JSON. Append, replace and read modes. Built for reliability: automatic retries, exponential backoff, no OAuth tokens that expire.

- **URL**: https://apify.com/surefetch/google-sheets.md
- **Developed by:** [Jonas Eckl](https://apify.com/surefetch) (community)
- **Categories:** Automation, Integrations, Developer tools
- **Stats:** 3 total users, 2 monthly users, 30.8% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 1,000 row processeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Google Sheets Import & Export — Fast, Reliable Sync

### What does Google Sheets Import & Export do?

This Actor moves data between Apify and Google Sheets in both directions: **import
Apify datasets, JSON or CSV into Google Sheets** (append or replace) and **export
Google Sheets to JSON** datasets. Use it as a standalone tool or as an
integration that pushes every scraper run's results straight into your sheet.

Built for one thing above all: **reliability**. No OAuth tokens that expire and
silently kill your scheduled runs — authentication works by sharing your sheet
with an import e-mail once, and it works forever.

### Why this Actor?

The most popular free alternative in the store fails **more than half of its
runs** (52% failure rate, public Apify run stats, August 2026) — mostly because
its Google OAuth tokens expire or get revoked between scheduled runs, producing
silent failure streaks until someone notices the missing data.

|  | This Actor | Popular free alternative |
|---|---|---|
| Run success rate | designed & monitored for >99% | ~48% (public stats, 08/2026) |
| Authentication | share sheet once, works forever | OAuth tokens that expire |
| Rate limits (429) | automatic exponential backoff | run fails |
| Empty source dataset | clean success (no-op) | run fails |
| Error messages | tell you exactly what to fix | stack traces |

### How does authentication work?

1. Run the Actor once — the log shows your **import e-mail**.
2. Open your sheet → **Share** → paste the e-mail → Editor → Done.
3. That's it, forever. No tokens, nothing expires, revoke anytime by unsharing.

Alternatives: bring your own Google service account key (stored encrypted), or
read public sheets with no authentication at all.

### How much does it cost?

Simple pay-per-event pricing — you only pay for what you process:

| What | Price (paid plans) |
|---|---|
| Actor start | $0.005 |
| 1,000 rows processed | + $0.01 |
| 10,000 rows | + $0.10 |
| 100,000 rows | + $1.00 |

A typical scraper-to-sheet sync costs about **$0.015 per run** — usually less
than the platform usage a failing "free" alternative burns on retries.

### Input

- **mode** — `read` (sheet → dataset), `append` (add rows below existing data)
  or `replace` (overwrite the sheet).
- **spreadsheetId** — full sheet URL or ID.
- **datasetId** — source dataset for write modes. Leave empty when running as an
  integration after another Actor: the triggering run's dataset is used
  automatically.
- **rawData** — inline JSON rows as an alternative source.
- **deduplicateByField**, **sheetName**, **maxRows** — optional fine-tuning.

Nested objects are flattened to `parent/child` columns; when appending, columns
are aligned to your existing header automatically.

### Output

`read` mode fills the run's dataset with one JSON object per sheet row (header
row = keys). Write modes push a summary item:

```json
{ "status": "ok", "written": 1250, "sheet": "Sheet1", "mode": "append" }
```

### Switching from another Google Sheets actor

Input field names (`mode`, `spreadsheetId`, `datasetId`, `rawData`,
`deduplicateByField`) match the established conventions — in most setups you
only swap the Actor and share your sheet with the import e-mail. Two minutes.

### FAQ

#### How do I export an Apify dataset to Google Sheets automatically?

Add this Actor as an **integration** to your scraper: Actor → Integrations →
Add integration → choose this Actor, set `mode: append` and your sheet URL.
Every successful run then appends its results to your sheet.

#### Can it read a public Google Sheet without authentication?

Yes — `read` mode works on any sheet shared as "Anyone with the link", with no
credentials at all.

#### Is my service account key safe?

Keys are stored encrypted by the Apify platform (`isSecret` input field) and
used only to access sheets you explicitly shared.

#### What are Google's limits?

Google caps spreadsheets at 10 million cells. The Actor checks this before
writing and tells you clearly instead of failing mid-import.

# Actor input Schema

## `mode` (type: `string`):

<b>append</b>: add dataset rows below existing data. <b>replace</b>: overwrite the whole sheet. <b>read</b>: export the sheet to a dataset (JSON).

## `spreadsheetId` (type: `string`):

Full URL (docs.google.com/spreadsheets/d/…) or just the ID.

## `sheetName` (type: `string`):

Optional. Defaults to the first tab.

## `datasetId` (type: `string`):

Dataset whose items are written to the sheet. Leave empty when this Actor runs as an integration after another Actor — the dataset of that run is used automatically.

## `rawData` (type: `array`):

Array of objects to write instead of a dataset. Max ~9 MB.

## `deduplicateByField` (type: `string`):

Optional. Keep only the first row per unique value of this field.

## `maxRows` (type: `integer`):

Safety cap on processed rows.

## `authMode` (type: `string`):

<b>auto</b> picks the right method: public read for public sheets in read mode, otherwise the share-with-import-e-mail method. No OAuth, no tokens that expire.

## `serviceAccountJson` (type: `string`):

Only for 'My own service account': paste the full JSON key. Stored encrypted. Share your sheet with the service account's client\_email.

## Actor input object example

```json
{
  "mode": "read",
  "spreadsheetId": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit",
  "maxRows": 250000,
  "authMode": "auto"
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "spreadsheetId": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit"
};

// Run the Actor and wait for it to finish
const run = await client.actor("surefetch/google-sheets").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "spreadsheetId": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit" }

# Run the Actor and wait for it to finish
run = client.actor("surefetch/google-sheets").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "spreadsheetId": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit"
}' |
apify call surefetch/google-sheets --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,surefetch/google-sheets"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/PZjfpiv9z8YisLwb7/builds/4j7CNn19Q1BOCXhZb/openapi.json