Google Sheets
Start agents from new rows in a Google Sheets spreadsheet and append their results as rows, through your own Google service account.
On this page
| Modes | Inbound, outbound |
| YAML type | google_sheets |
| Credentials | A Connection of type gmail, shown as Google Workspace in the dashboard, with the JSON key of your own Google service account. Gmail connectors can use the same Connection. |
| Spreadsheets | Spreadsheets shared with the service account's email address |
| Bridge | Not supported |
| Custom domain | Not supported |
| Linked agents | One or more. A new row starts every linked agent. |
| While paused | Inbound stops checking the sheet. Rows added meanwhile are processed after Resume. Outbound appends nothing. |
Set up
Create a service account with a JSON key in a Google Cloud project that has the Google Sheets API enabled. Share the spreadsheet with the service account's email address: Viewer for inbound, Editor for outbound.
Open the agent. In Connector Flow, click Add inbound connector for inbound or Add outbound connector for outbound. Then click Create New Connector and choose Google Sheets.
Choose the mode. Under Connection, pick a saved Google Workspace Connection or create one with the contents of the key file.
Enter the Spreadsheet and, for a sheet other than the first, the Sheet.
Click Create. An inbound connector starts checking the sheet. For outbound, choose how the agent uses the connector and click Link connector.
In code
Declare the connector in connectors/*.yaml. connection names the Connection that holds the service account key.
type: google_sheets
mode: inbound
connection: acme-google # Google Workspace Connection with the service account key
config:
spreadsheet: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
sheet: Leads
agents:
- lead-qualifiertype: google_sheets
mode: outbound
connection: acme-google
config:
spreadsheet: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
sheet: Qualified
agents:
- name: lead-qualifier
outbound: { usage: automatic }Configuration
The fields of a Google Sheets connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.
| Field | Type | Status | Description |
|---|---|---|---|
| type | string | Required | google_sheets. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Required | Name or ID of a Connection of type gmail. See Service account. Dashboard: Connection. |
| config | object | Required | Google Sheets settings. |
| spreadsheet | string | Required | The URL of the spreadsheet, such as https://docs.google.com/spreadsheets/d/<ID>/edit, or its ID. connic stores the ID. Dashboard: Spreadsheet. |
| sheet | string | Optional | The name of the sheet, exactly as on its tab. Without it, the connector uses the first sheet. Dashboard: Sheet. |
Agent input
Modes: Inbound
An inbound connector checks the sheet about every minute and starts a run for every linked agent with each new row. Row 1 holds the column names. At its first check, the connector starts after the sheet's last row; rows that were already there aren't processed. Empty rows are skipped. Changing the spreadsheet or the sheet starts again at that moment. The run receives the row like this:
{
"row": {
"Name": "Jane Doe",
"Email": "jane@example.com",
"Company": "Example Ltd",
"Message": "We need 40 seats from January."
},
"row_number": 12,
"_google_sheets": {
"connector_id": "550e8400-e29b-41d4-a716-446655440000",
"spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"sheet": "Leads",
"row_number": 12,
"timestamp": "2026-10-12T08:30:05.123456"
}
}rowhas one key per column name in row 1. Values arrive as text, formatted the way the sheet shows them, such as a date or an amount with its currency.- A column without a name, or with a name an earlier column already uses, appears under its column letter, such as
C. Empty cells at the end of the row are left out. row_numberis the row's number in the sheet when connic read it._google_sheetsnames the connector, the spreadsheet ID, the sheet, and the row number.
Adding rows
connic processes a row the first time it sees it, so add each row in one go, for example from a form, a script, or by pasting it. A row typed cell by cell can start a run with only its first cells filled in. Changes to rows that were already processed start nothing.
When rows are inserted or deleted above the last processed row, connic finds that row at its new place by its values and goes on after it. If that row was changed or deleted, the logs show a warning, and connic goes on after the same row number, or after the last row when the sheet got shorter.
Service account
Google Sheets connectors use the same Google Workspace Connection as Gmail; its page describes how to create the service account and its key. Enable the Google Sheets API in the service account's project. Google Sheets connectors don't need domain-wide delegation: the service account opens the spreadsheet as itself, so it needs access to each spreadsheet.
Copy the service account's email address. It's the
client_emailin the key file and ends in.iam.gserviceaccount.com.In the spreadsheet, click Share and add that address: as Viewer for an inbound connector, as Editor for an outbound one.
If the sharing settings for Google Drive in your Google Workspace block sharing outside the organization, an admin has to allow it for that address.
Outbound delivery
Modes: Outbound
An outbound Google Sheets connector appends one row below the sheet's data each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. connic inserts the new row, so nothing below the data is overwritten.
Each key of the row names a column in row 1, matched exactly after spaces around the column name are trimmed. A column without a name, or with a name an earlier column already uses, is named by its letter, such as C. Missing keys leave their cells empty. A key that isn't a column fails the delivery, and the error names the keys. Values are written as they are: text that starts with = stays text and never runs as a formula, null leaves the cell empty, and objects and lists are written as JSON text.
Automatic output
An automatic link appends the run's final output, which must be a JSON object. Any other output fails the delivery with The agent output must be a JSON object whose keys name columns in the sheet's first row. Give the agent an output schema that returns the columns. This output fills four columns of the new row:
{
"Name": "Jane Doe",
"Email": "jane@example.com",
"Score": 82,
"Next step": "Book a demo"
}Agent-tool and middleware payload
The model or middleware passes the columns under row. row is required and any other field is rejected. connic adds the spreadsheet, the sign-in, and the retries, none of which the model sees.
{
"row": {
"Name": "Jane Doe",
"Score": 82,
"Next step": "Book a demo"
}
}Delivery and retries
connic signs in as the service account, reads the column names from row 1, and appends the row. When Google Sheets can't be reached or rate-limits the request, connic tries again, 3 times in total, waiting as long as Google asks. Any other error fails the delivery without a retry. If the connection breaks after the row was sent, or Google answers with a server error, connic can't tell whether the row was added and doesn't retry, so it's never added twice; check the sheet. The connector's runs show each delivery with its error.
Limits and errors
| Limit | Value |
|---|---|
| Sheet checks | About every minute |
| Rows per check | 500. The rest follow in the next check. |
| Delivery attempts | 3, only when Google Sheets can't be reached or rate-limits the request |
| Google Sheets API limits | 60 read and 60 write requests per minute per user and Google Cloud project, where the service account is the user, and 300 of each per project, per the Sheets API usage limits. Each check uses two read requests, each appended row one read and one write. Connectors on the same service account share these limits. |
When Google rejects the sign-in, for example because the key was deleted, or when the spreadsheet isn't shared with the service account or the Google Sheets API isn't enabled (403), the spreadsheet ID is wrong (404), or the sheet doesn't exist, the connector's logs show Polling stopped with the reason, and connic stops checking until you save the connector or its Connection again. Rate limits, network errors, and server errors appear as Poll error; connic keeps trying and waits longer after each failure, up to 15 minutes.
Every processed row appears in the connector's runs with the number of agents it started. If a run can't be started, connic reads the row again on the next check; agents that already received it don't get a second run.