Skip to main content
connic
Connectors

Google Sheets

Start agents from new rows in a Google Sheets spreadsheet and append their results as rows, through your own Google service account.

Last updated
ModesInbound, outbound
YAML typegoogle_sheets
CredentialsA 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.
SpreadsheetsSpreadsheets shared with the service account's email address
BridgeNot supported
Custom domainNot supported
Linked agentsOne or more. A new row starts every linked agent.
While pausedInbound stops checking the sheet. Rows added meanwhile are processed after Resume. Outbound appends nothing.

Set up

  1. 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.

  2. 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.

  3. Choose the mode. Under Connection, pick a saved Google Workspace Connection or create one with the contents of the key file.

  4. Enter the Spreadsheet and, for a sheet other than the first, the Sheet.

  5. 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.

connectors/new-leads.yaml
type: google_sheets
mode: inbound
connection: acme-google   # Google Workspace Connection with the service account key
config:
  spreadsheet: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
  sheet: Leads
agents:
  - lead-qualifier
connectors/qualified-leads.yaml
type: 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.

FieldTypeStatusDescription
typestringRequiredgoogle_sheets.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredName or ID of a Connection of type gmail. See Service account. Dashboard: Connection.
configobjectRequiredGoogle Sheets settings.
spreadsheetstringRequiredThe URL of the spreadsheet, such as https://docs.google.com/spreadsheets/d/<ID>/edit, or its ID. connic stores the ID. Dashboard: Spreadsheet.
sheetstringOptionalThe 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:

payload.json
{
  "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"
  }
}
  • row has 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_number is the row's number in the sheet when connic read it. _google_sheets names 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.

  1. Copy the service account's email address. It's the client_email in the key file and ends in .iam.gserviceaccount.com.

  2. 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:

output.json
{
  "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.

connector-payload.json
{
  "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

LimitValue
Sheet checksAbout every minute
Rows per check500. The rest follow in the next check.
Delivery attempts3, only when Google Sheets can't be reached or rate-limits the request
Google Sheets API limits60 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.