Docs
Connections

Google Sheets

Connect Google Sheets with Google consent, choose the spreadsheets Xentropy may read, and read bounded A1 ranges into datasets.

A Google Sheets connection reads ranges of the spreadsheets you choose. Consent happens on Google's consent screen in your browser, and Xentropy asks only for the drive.file scope: it can open the files you pick and nothing else in your Google Drive.

Set up the connection

Open Connections, choose New connection, then Google Sheets.
Sign in with Google and approve access to the files you choose.
Choose Choose spreadsheets and pick the spreadsheets that datasets and agents may read in Google's file picker.
Open a spreadsheet's resources, enter a range, preview it and save a dataset.

A connection holds up to 100 chosen files. A dataset can only read a chosen spreadsheet. Reads of any other file fail with PERMISSION_DENIED. If a spreadsheet is removed from the connection during a read, that read fails too.

Agents cannot give consent. An agent with connections:manage can start the flow, but the owner finishes it in a browser.

Ranges

A dataset reads one explicit A1 rectangle, such as Sheet1!A1:F200. Quote tab names that contain spaces or symbols: 'Q3 targets'!A1:D50.

LimitValue
Cells per range10,000 cells
Columns per range100 columns
Rows per range1,000
Response size8 MB
Request timeout20 s

For a larger sheet, save several datasets with separate bounded ranges.

Header row

The first row of the range is the header row. Every header cell must be a unique, non-empty text value, otherwise the read fails with VALIDATION_FAILED. Column types come from the values in the range. Once a dataset is saved, its fields are fixed: if a selected column is removed or renamed in the sheet, refreshes fail with SCHEMA_CHANGED.

Refreshes and connection health

Every refresh reads the range again. A successful test or read marks the connection healthy. When Google refuses a read, the connection's health records why: a missing permission, or a temporary error such as a rate limit.

If you revoke Xentropy's access in your Google account, or Google expires the grant, the connection needs a reconnect. The read that finds out fails with INVALID_GRANT. Later reads fail with RECONNECT_REQUIRED until you reconnect, and Xentropy does not call Google in the meantime.

Rate limits

Google limits read requests per user and per project. When a limit is reached, whether Google answers HTTP 429 or a quota 403 such as rateLimitExceeded, the read fails with PROVIDER_UNAVAILABLE and HTTP status 429. The error is retryable. When Google says how long to wait, details.retryAt holds that time. A quota limit does not mark the connection as missing permission.

Errors

CodeCauseWhat to do
PROVIDER_RANGE_INVALIDGoogle could not read the range: an unknown tab, or a range outside the sheetCheck the tab name and the A1 rectangle
LIMIT_EXCEEDEDThe range is larger than 10,000 cells or 100 columns, or the response exceeds 8 MBRead smaller ranges
VALIDATION_FAILEDThe header row is missing, empty or has duplicate namesFix the header row
SCHEMA_CHANGEDA selected column was removed from the sheetRestore the column, or save a new dataset
PROVIDER_FILE_NOT_FOUNDThe spreadsheet was deleted, or is no longer shared with your accountRestore the file, or choose another one
MISSING_PROVIDER_SCOPEGoogle denied access to the file, for example because of an account policyCheck the file's sharing and your organization's policy, then reconnect
INVALID_GRANT, then RECONNECT_REQUIREDAccess was revoked or the grant expiredReconnect the connection
PROVIDER_UNAVAILABLE (429)Google's rate limit or quota was reachedRetry after details.retryAt, or later. Do not retry in a loop
PROVIDER_UNAVAILABLE (503)Google could not be reached or answered with an errorRetry the read later
PERMISSION_DENIEDThe spreadsheet is not chosen on this connectionChoose it with Choose spreadsheets

On this page