Google Sheets for AI Agents — Read, Append, Replace

Read, append, replace or clear any Google Sheet in one step. No OAuth popups, no Google Cloud setup. Paste the sheet link, share the sheet with one email address, and run.

Built to be reliable for AI agents (Claude, ChatGPT, Cursor via the Apify MCP server), Apify integrations, Make/Zapier/n8n and scheduled runs.

Setup in 30 seconds

1. Open your Google Sheet → click Share.
2. Add sheets-bot@sheets-bot-512104.iam.gserviceaccount.com as an Editor (Viewer is enough if you only read).
3. Paste the sheet URL into this Actor and pick an action.

That's it. If you forget step 2, the run tells you exactly what to do.

What it does

Action	What happens
read	Returns every row as JSON. Row 1 is used as field names.
append	Adds rows to the bottom (from rows or from another Actor's dataset). Object keys are matched to your existing columns (case-insensitive). New keys become new columns automatically.
replace	Clears the tab (or a range) and writes your rows. Validates your data before clearing, so a bad input never wipes your sheet.
clear	Empties the tab or a range.
listTabs	Lists the tabs in the spreadsheet.

Why this one

• Appends never overwrite. Append always adds below your existing data.
• Plain-English errors. "Share the sheet with … as an Editor", "Tab 'Leads2' not found. Available tabs: 'Leads', 'Archive'" — so an AI agent can fix the problem itself.
• Accepts whatever you have. Full URL or just the ID, tab by name or from the #gid= in the link, rows as objects, arrays, or a JSON string.
• Safe by default. Values are stored exactly as sent (RAW), so scraped text like =IMPORTXML(...) can never execute as a formula. Switch to USER_ENTERED if you want Sheets to parse formulas and dates.
• Big writes just work. Large batches are split automatically, and Google rate limits are retried with backoff.
• Creates missing tabs on append/replace.

Examples

Append leads from another Actor or an AI agent

{
  "spreadsheet": "https://docs.google.com/spreadsheets/d/1AbC.../edit",
  "action": "append",
  "sheetName": "Leads",
  "rows": [
    { "name": "Ann Lee", "email": "ann@example.com", "company": "Acme" },
    { "name": "Bo Chan", "email": "bo@example.com", "city": "Ottawa" }
  ]
}

If Leads has columns name | email | company, a city column is added for Bo.

Read a tab as JSON

{ "spreadsheet": "1AbC...", "action": "read", "sheetName": "Leads", "maxRows": 500 }

Output (dataset):

[{ "name": "Ann Lee", "email": "ann@example.com", "company": "Acme", "city": "" }]

Overwrite a report tab every day (schedule this run)

{ "spreadsheet": "1AbC...", "action": "replace", "sheetName": "Daily report", "rows": [ ... ] }

Use it from an AI agent (MCP)

Connect your agent to https://mcp.apify.com and add this Actor as a tool. The inputs are simple enough for an agent to fill in: spreadsheet, action, sheetName, rows.

Send any scraper's results to Sheets automatically

Run this Actor every time another Actor finishes, so its results land in your sheet with no clicking:

1. Open your scraper (Google Maps, Instagram, anything) → Integrations tab → Add integration → pick this Actor.
2. Use this input:

{
  "spreadsheet": "https://docs.google.com/spreadsheets/d/1AbC.../edit",
  "action": "append",
  "sheetName": "Leads",
  "datasetId": "{{resource.defaultDatasetId}}"
}

3. Schedule the scraper. Each run appends its new results to the sheet.

Good to know:

• Nested fields get their own columns (address.city, address.zip) instead of a blob of JSON. Turn off Flatten nested fields to keep them as JSON.
• Pick columns with datasetFields, e.g. ["title", "phone", "address.city"]. They're written in that order.
• Want a fresh copy each time? Use "action": "replace". If the scraper run returns nothing, your sheet is left untouched instead of wiped.

You can also copy any existing dataset by pasting its ID into Dataset ID.

Output

• read and listTabs: the rows/tabs are in the dataset.
• Every run saves a summary to the OUTPUT record, e.g. { "ok": true, "action": "append", "sheetName": "Leads", "rowsWritten": 2, "headers": ["name","email","company","city"] }
• Write actions also push that summary to the dataset, so agents see the result directly.

Pricing

Pay per event: you're charged per row read or written. Listing tabs and clearing are not charged beyond the small run start fee. Set a max cost per run and the Actor stops at your limit instead of overspending.

Privacy and security

• The Actor only touches sheets you explicitly share with it, and only for the run you start.
• Sheet contents aren't stored anywhere except your own run's dataset.
• Prefer not to share with a shared bot? Paste your own Google Cloud service account key in Advanced → Your own service account key (stored encrypted) and share the sheet with that account instead.

Limits (Google's, not ours)

• 10 million cells per spreadsheet.
• Very large reads may be slow; use range or maxRows to fetch only what you need.

Questions or bugs

Open an issue on the Issues tab. Fast replies.