Google Sheets Import and Export
Pricing
from $8.50 / 1,000 rows written, per block of up to 100s
Google Sheets Import and Export
Read a Google Sheet into an Apify dataset, or write an Apify dataset or a list of rows into a Google Sheet: append, replace, or update rows by a key column. Works on your own Google service account or OAuth token; a sheet shared as anyone with the link reads with no credential.
Pricing
from $8.50 / 1,000 rows written, per block of up to 100s
Rating
0.0
(0)
Developer
Mamba Labs
Maintained by CommunityActor stats
0
Bookmarked
2
Total users
1
Monthly active users
9 minutes ago
Last modified
Categories
Features
Share
Read a Google Sheet into an Apify dataset, or write an Apify dataset or a list of rows into a Google Sheet. Read mode returns one row per sheet row, keyed by the header row. Append, replace, and upsert modes write rows into a tab, add new columns to the header as they appear, and in upsert mode overwrite the rows whose key column value is already in the sheet. Writes run on your own Google credential: a service account key or an OAuth token. A sheet shared as "anyone with the link" reads with no credential. You pay per block of up to 100 rows.
Features
- Read any tab into JSON rows keyed by its header row, with the sheet row number on each row. Pick the tab by name, by gid, or by the gid in the URL, and limit the read to an A1 range.
- Export an Apify dataset to a sheet: pass the dataset ID, or {{resource.defaultDatasetId}} from an Apify integration, and every item becomes a sheet row.
- Append, replace, or upsert. Append adds rows after the last row. Replace clears the tab, then writes. Upsert overwrites the rows whose
key_columnvalue already exists and adds the rest. - Header matching. Your row keys are matched to the sheet's header columns, whatever their order. A key the header does not have becomes a new column at the end.
- Safe values. Values are stored as plain text by default, so a scraped value that starts with
=is not run as a formula. Setvalue_inputtouser_enteredto have Google parse formulas, dates, and numbers. - Never bills a write it could not deliver. Before each write the actor checks your charge limits, and it never writes a block of rows it could not charge.
How the data is read
The actor calls the Google Sheets API v4 (sheets.googleapis.com) with your own credential. A service account key is exchanged for a one hour access token at oauth2.googleapis.com; a refresh token is exchanged the same way with its OAuth client. Your credential is sent only to Google and is never stored, logged, or written to a row. With no credential, read mode fetches Google's own CSV export of a sheet shared as "anyone with the link". No proxy, no browser, and no other developer's actor. Your use of the Sheets API runs on your own Google project under Google's API terms.
Setting up a service account. In Google Cloud, create a service account, enable the Google Sheets API on its project, create a JSON key, and paste the whole file into service_account_json. Then share the spreadsheet with the service account's client_email as an Editor (a Viewer is enough to read).
Testing. Read mode on a public sheet was tested live on 2026-11-17. The write modes and the credential routes were tested against recorded Google responses and a refused key path from inside an Apify run. The first buyer's credential is the live test of the write path.
Input
| Field | Type | Default | What it does |
|---|---|---|---|
mode | string | read | read (default): the sheet becomes one dataset row per sheet row. append: add rows after the last row. replace: clear the tab, then write the rows. upsert: overwrite the rows whose key_column value is already in the sheet and add the rest. The three write modes need a credential below. |
spreadsheet | string | The Google Sheets URL as copied from the browser, or the spreadsheet ID. A #gid= in the URL picks that tab. | |
sheet | string | Optional. The tab name, or its gid number. Default: the gid in the URL, else the first tab. In a write mode a tab name that does not exist is created. | |
range | string | Optional, read mode. An A1 range without the tab name, for example A1:F500 or B:D. Default: the whole tab. | |
header_row | string | true | true (default) or false. When true, read rows are keyed by the header row, and writes match your row keys to the header columns and add new columns at the end. When false, read rows are keyed by column letter and writes go column by column in key order. |
dataset_id | string | Write modes. The Apify dataset whose items go into the sheet, for example the default dataset of another run. In an Apify integration, pass the triggering run's resource.defaultDatasetId variable. Fields starting with # are skipped. | |
rows | array | Write modes, instead of a dataset. A JSON list of objects, one per sheet row, for example [{"name": "Ann", "email": "ann@example.com"}]. | |
columns | array | Optional, write modes. Only these keys are written, in this order. Default: every key in the rows, in first seen order. | |
key_column | string | Upsert mode. The column whose value identifies a row, for example email or url. A row whose value is already in that column is overwritten in place; the rest are added. Rows with no value in it are skipped. | |
value_input | string | raw | raw (default): every value is stored exactly as given, so text starting with = is not run as a formula. user_entered: Google parses values as if typed, so formulas run and dates and numbers are converted. |
max_rows | string | 100000 | Most rows to read or write in this run, 1 to 1,000,000 (default 100,000). |
service_account_json | string | Your own service account key file, pasted whole. Share the spreadsheet with its client_email as an Editor (Viewer to read). It is sent only to Google and is never stored, logged, or written to a row. | |
oauth_refresh_token | string | Instead of a service account: a refresh token from your own Google OAuth client with the spreadsheets scope. Needs oauth_client_id and oauth_client_secret from the same client. | |
oauth_client_id | string | The client ID that issued the refresh token. | |
oauth_client_secret | string | The client secret that issued the refresh token. | |
oauth_access_token | string | Instead of the above: a current OAuth access token with the spreadsheets scope. It expires in about an hour, so it suits a single run. | |
max_charge_usd | string | Optional. The run stops before a charge that would pass this amount, and never writes a block of rows it could not charge. Summary rows are always returned. |
Output
| Field | Type | What it holds |
|---|---|---|
row_type | string | One of: sheet_row, read_receipt, write_receipt, run_summary. run_summary is the one free row written when the input is refused. |
spreadsheet_id | string | The ID of the spreadsheet, from its URL. |
sheet | string | The tab the run read or wrote, by name. A public read by gid shows the gid. |
mode | string | read, append, replace, or upsert, as run. |
access | string | How the actor reached the sheet: public_link (no credential, a sheet shared as anyone with the link), service_account, refresh_token, or access_token. |
row_number | integer | On a sheet_row: the row number in the sheet, from 1. |
values | object | On a sheet_row: the row as column name to cell text, using the header row. With header_row off, the keys are column letters. |
cells | array | On a sheet_row: the row's cells in column order, as text. |
rows_in_block | integer | On a receipt: how many rows this billed block covers, 1 to 100. |
range | string | On a receipt: the sheet range read or written, as Google reported it. |
rows_read | integer | On the summary row: sheet rows delivered in this run. |
rows_written | integer | On the summary row: rows written to the sheet in this run, updated plus appended. |
rows_updated | integer | On the summary row in upsert mode: existing rows overwritten in place. |
rows_appended | integer | On the summary row: rows added as new sheet rows. |
row_status | string | ok, or why this row carries no data: no_results, no_change, partial, blocked, or error. |
error_reason | string | Why the row is not ok. A refused input reads input_invalid: followed by what to fix. |
billable_events_json | string | What this row was billed as, for example {"rows-written":1}. {} means free. |
scraped_at | string | When the row was written, UTC. |
Row types: sheet_row (one per sheet row in read mode, free), read_receipt (one per block of up to 100 rows read, billed), write_receipt (one per block of up to 100 rows written, billed), and run_summary (one per run, free). To work with only the sheet data, filter the dataset to row_type sheet_row.
Pricing
Pay per event. Mamba Labs pays the platform costs of the run. Summary rows, empty reads and writes, a refused credential, and a refused input are free.
| Event | Free plan | Bronze | Silver | Gold |
|---|---|---|---|---|
rows-written, one block of up to 100 rows written to your sheet | $0.01 | $0.0095 | $0.009 | $0.0085 |
rows-read, one block of up to 100 sheet rows read into the dataset | $0.005 | $0.00475 | $0.0045 | $0.00425 |
apify-actor-start, once per run (one per GB of memory; the default 256 MB is one) | $0.002 | $0.002 | $0.002 | $0.002 |
Per 1,000 rows of rows-written (10 blocks of 100): $0.10 on the free plan, $0.09 on Gold.
Free plan cap: 1.50 USD of evaluation a month, about 15000 rows. Any paid Apify plan removes the cap, and it resets on the 1st. The run stops before a charge that passes your maximum charge per run in Apify or your max_charge_usd input.
Mamba Labs pays the platform costs of your run, Apify proxy traffic included.
A write of 250 rows is 3 blocks. A read of 1,000 rows is 10 blocks.
Usage examples
Export a dataset after every run. Add this actor as an integration on another actor, with mode append, your spreadsheet URL, dataset_id {{resource.defaultDatasetId}}, and your service account key.
Keep a sheet in sync. Run with mode upsert and key_column url (or email, or any column that identifies a row). Rows already in the sheet are updated in place; new ones are added.
Clay. Number and on or off inputs are text fields, which is what Clay sends. A list input takes a JSON list, so put the column inside a one item list. rows also takes JSON text.
MCP. The Mamba Labs MCP server @mambalabsdev/mcp-google-sheets-import-export exposes this actor to Claude and other MCP clients.
Error handling
| Case | What you get |
|---|---|
| Missing or unreadable input | One free row, row_type run_summary, error_reason starting input_invalid: with what to fix. The run ends successfully and charges nothing but the run start (apify-actor-start) |
| Google refuses the credential | One free run_summary row with row_status blocked and error_reason starting key_refused: with Google's reason. Nothing is written |
| The credential has no access to the sheet | One free blocked row starting no_access:. For a service account it names the email to share the sheet with |
| A private sheet with no credential | One free blocked row that says to share it as "anyone with the link" or give a credential |
| No spreadsheet or tab with that ID or name | One free no_results row starting not_found:. In a write mode, a tab name that does not exist is created instead |
| The Sheets API rate limit | The actor waits and retries up to 4 times, then stops with a free blocked row. Rows already written stay written and billed |
| Your charge limit is reached | The run stops before the next block, writes nothing it could not charge, and the summary row says from which position rows were not written |
| The run is close to its timeout | The actor stops starting new work 90 seconds before the timeout and delivers what it has |
Limitations
- Read mode returns the cell text as shown in the sheet (formatted values), not the formulas.
- A public read by tab name uses Google's gviz export. It can return empty cells in a column that mixes numbers and text, it leaves out rows hidden by a filter left on the tab, and a tab name that does not exist returns the first tab instead of an error. Read by gid (the number after
#gid=in the URL) to avoid all three; that uses the CSV export. Reads with a credential use the Sheets API and do not have these limits. - Upsert matches on exact text after trimming spaces. Rows with no value in
key_columnare skipped and counted on the summary row. Inside one write, the last row with a given key wins. - Objects and lists in your rows are written as JSON text. A cell holds at most 50,000 characters; longer values are cut, and the summary row counts them.
- Replace clears the whole tab, formatting kept, values removed.
- The Google Sheets API allows 60 write requests a minute per user by default. The actor writes up to 500 rows per request and waits when Google asks it to.
- An OAuth access token expires in about an hour. For runs longer than that, use a service account key or a refresh token.
Mamba Labs actor suite
Built by Mamba Labs.