Skip to content
Scalekit Docs
Talk to an EngineerDashboard

Google Sheets connector

OAuth 2.0Files & DocumentsAnalytics

Connect to Google Sheets. Create, edit, and analyze spreadsheets with powerful data management capabilities

Google Sheets connector

  1. Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Register your Google Sheets credentials with Scalekit so it handles the token lifecycle. You do this once per environment.

    Dashboard setup steps

    Register your Scalekit environment with the Google Sheets connector so Scalekit handles the authentication flow and token lifecycle for you. The connection name you create will be used to identify and invoke the connection programmatically. Then complete the configuration in your application as follows:

    1. Set up auth redirects

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Google Sheets and click Create. Click Use your own credentials and copy the redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

        Copy redirect URI from Scalekit dashboard

      • Navigate to Google Cloud ConsoleAPIs & ServicesCredentials. Select + Create Credentials, then OAuth client ID. Choose Web application from the Application type menu.

        Select Web Application in Google OAuth settings

      • Under Authorized redirect URIs, click + Add URI, paste the redirect URI, and click Create.

        Add authorized redirect URI in Google Cloud Console

    2. Enable the Google Sheets API

      • In Google Cloud Console, go to APIs & ServicesLibrary. Search for “Google Sheets API” and click Enable.
    3. Get client credentials

      • Google provides your Client ID and Client Secret after you create the OAuth client ID in step 1.
    4. Add credentials in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections and open the connection you created.

      • Enter your credentials:

        Add credentials in Scalekit dashboard

      • Click Save.

  4. quickstart.ts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENV_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'googlesheets'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Google Sheets:', link)
    process.stdout.write('Press Enter after authorizing...')
    await new Promise(r => process.stdin.once('data', r))
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'googlesheets_read_spreadsheet',
    toolInput: { spreadsheet_id: 'YOUR_SPREADSHEET_ID' },
    })
    console.log(result)

Connect this agent connector to let your agent:

  • Chart add — Add a basic chart (column, bar, line, area, scatter, or combo) to a Google Sheet, built from a labeled range of source data
  • Format add conditional — Add a conditional formatting rule to a range in a Google Sheet, applying bold text formatting when the specified condition is met
  • Sheet add, duplicate, rename — Add a new sheet (tab) to an existing Google Sheets spreadsheet, with an optional position and grid size
  • Values append, batch clear, clear — Append rows of data to a Google Sheets spreadsheet
  • Get batch, values — Return cell values for multiple ranges of a Google Sheet in a single request
  • Update batch, values — Update values across multiple ranges of a Google Sheet in a single request
Proxy API call
const result = await actions.request({
connectionName: 'googlesheets',
identifier: 'user_123',
path: '/v4/spreadsheets',
method: 'GET',
});
console.log(result);
googlesheets_create_spreadsheet

Create a new Google Sheets spreadsheet with an optional title and initial sheet configuration. Returns the new spreadsheet ID and metadata.

NameTypeRequiredDescription
localestringNoLocale of the spreadsheet
schema_versionstringNoOptional schema version to use for tool execution
sheetsarray<object>NoInitial sheets to include in the spreadsheet
time_zonestringNoTime zone for the spreadsheet
titlestringNoTitle of the new spreadsheet
tool_versionstringNoOptional tool version to use for execution
googlesheets_get_values

Returns only the cell values from a specific range in a Google Sheet — no metadata, no formatting, just the data. For full spreadsheet metadata and formatting, use googlesheets_read_spreadsheet instead.

NameTypeRequiredDescription
major_dimensionstringNoWhether values are returned by rows or columns
rangestringYesCell range to read in A1 notation
schema_versionstringNoOptional schema version to use for tool execution
spreadsheet_idstringYesThe ID of the Google Sheet
tool_versionstringNoOptional tool version to use for execution
value_render_optionstringNoHow values should be rendered in the response
googlesheets_read_spreadsheet

Returns everything about a spreadsheet — including spreadsheet metadata, sheet properties, cell values, formatting, themes, and pixel sizes. If you only need cell values, use googlesheets_get_values instead.

NameTypeRequiredDescription
include_grid_databooleanNoInclude cell data in the response
rangesstringNoCell range to read in A1 notation
schema_versionstringNoOptional schema version to use for tool execution
spreadsheet_idstringYesThe ID of the Google Sheet to read
tool_versionstringNoOptional tool version to use for execution
googlesheets_update_values

Update cell values in a specific range of a Google Sheet. Supports writing single cells or multiple rows and columns at once.

NameTypeRequiredDescription
include_values_in_responsebooleanNoReturn the updated cell values in the response
rangestringYesCell range to update in A1 notation
schema_versionstringNoOptional schema version to use for tool execution
spreadsheet_idstringYesThe ID of the Google Sheet to update
tool_versionstringNoOptional tool version to use for execution
value_input_optionstringNoHow input values should be interpreted
valuesarray<array>Yes2D array of values to write to the range
Execute a tool
const result = await actions.executeTool({
connector: 'googlesheets',
identifier: 'user_123',
toolName: 'googlesheets_get_values',
toolInput: {
spreadsheet_id: '<SPREADSHEET_ID>',
range: 'Sheet1!A1:D10',
},
});
console.log(result);
Google OAuth consent screen verification

Before you use your own Google OAuth credentials in production, understand what end users see on Google’s consent screen when they authorize a connected account.

Audience typeConsent screen behaviorWhen to use
InternalShows your App Name and logo from Branding settingsOnly users in your Google Workspace or Cloud Identity organization can authorize the connector
ExternalShows {env_name}.scalekit.dev until Google verifies your appAny user with a Google account can authorize the connector

Why External is required for most AgentKit connectors:

  • Internal restricts authorization to users in your Google Workspace or Cloud Identity organization. Users with @gmail.com or other Google accounts outside your organization cannot complete OAuth.
  • External is required when end users outside your organization authorize tool access through connected accounts.
  • Organization-managed OAuth clients follow the same rules as personal or developer OAuth clients. Switching to an org-owned client does not bypass Google verification.
  • Until Google completes verification of your External app, users see scalekit.dev on the consent screen. After verification, your App Name and logo appear.

During development:

  • Add Test users under APIs & Services → OAuth consent screen while publishing status is Testing.
  • On unverified apps, users can click Advanced → Go to app (unsafe) to proceed during testing.
  • Google Workspace admins may need to allowlist your OAuth client.

For Google’s verification requirements and timeline, refer to Google’s OAuth consent screen verification guide.

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

googlesheets_add_chart#Add a basic chart (column, bar, line, area, scatter, or combo) to a Google Sheet, built from a labeled range of source data. The chart is placed on a new sheet.10 params

Add a basic chart (column, bar, line, area, scatter, or combo) to a Google Sheet, built from a labeled range of source data. The chart is placed on a new sheet.

NameTypeRequiredDescription
chart_typestringrequiredThe type of chart to create
end_column_indexintegerrequiredThe zero-based end column index (exclusive) of the data range, including the value columns
end_row_indexintegerrequiredThe zero-based end row index (exclusive) of the data range
sheet_idintegerrequiredThe ID of the sheet (tab) holding the source data for the chart
spreadsheet_idstringrequiredThe ID of the Google Sheet to modify
start_column_indexintegerrequiredThe zero-based start column index of the data range. This column is used as the chart's domain (labels/categories)
start_row_indexintegerrequiredThe zero-based start row index of the data range
schema_versionstringoptionalOptional schema version to use for tool execution
titlestringoptionalTitle displayed on the chart
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_add_conditional_format#Add a conditional formatting rule to a range in a Google Sheet, applying bold text formatting when the specified condition is met.11 params

Add a conditional formatting rule to a range in a Google Sheet, applying bold text formatting when the specified condition is met.

NameTypeRequiredDescription
condition_typestringrequiredThe type of condition that triggers the formatting
end_column_indexintegerrequiredThe zero-based end column index (exclusive) of the range
end_row_indexintegerrequiredThe zero-based end row index (exclusive) of the range
sheet_idintegerrequiredThe ID of the sheet (tab) containing the range
spreadsheet_idstringrequiredThe ID of the Google Sheet to modify
start_column_indexintegerrequiredThe zero-based start column index of the range
start_row_indexintegerrequiredThe zero-based start row index of the range
boldbooleanoptionalWhether matching cells should be formatted bold
condition_valuestringoptionalThe comparison value used by the condition (not needed for BLANK/NOT_BLANK)
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_add_sheet#Add a new sheet (tab) to an existing Google Sheets spreadsheet, with an optional position and grid size.7 params

Add a new sheet (tab) to an existing Google Sheets spreadsheet, with an optional position and grid size.

NameTypeRequiredDescription
spreadsheet_idstringrequiredThe ID of the spreadsheet to add a sheet to
titlestringrequiredTitle of the new sheet
column_countintegeroptionalNumber of columns for the new sheet's grid
indexintegeroptionalZero-based position at which to insert the new sheet
row_countintegeroptionalNumber of rows for the new sheet's grid
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_append_values#Append rows of data to a Google Sheets spreadsheet. Data is added after the last row with existing content in the specified range.5 params

Append rows of data to a Google Sheets spreadsheet. Data is added after the last row with existing content in the specified range.

NameTypeRequiredDescription
rangestringrequiredThe A1 notation range to append data to (e.g. Sheet1!A1)
spreadsheet_idstringrequiredThe ID of the spreadsheet to append data to
valuesarrayrequired2D array of values to append. Each inner array is a row.
insert_data_optionstringoptionalHow the input data should be inserted. Options: INSERT_ROWS (inserts new rows), OVERWRITE (overwrites existing data). Default: OVERWRITE
value_input_optionstringoptionalHow input data should be interpreted. Options: RAW (literal values), USER_ENTERED (as if typed in UI, parses formulas/dates). Default: USER_ENTERED
googlesheets_batch_clear_values#Clear all values across multiple ranges of a Google Sheet in a single request. Formatting is preserved; only the cell values are cleared.4 params

Clear all values across multiple ranges of a Google Sheet in a single request. Formatting is preserved; only the cell values are cleared.

NameTypeRequiredDescription
rangesarrayrequiredList of A1 notation ranges to clear
spreadsheet_idstringrequiredThe ID of the spreadsheet to clear values in
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_batch_get_values#Return cell values for multiple ranges of a Google Sheet in a single request. More efficient than calling googlesheets_get_values repeatedly when you need several ranges at once.6 params

Return cell values for multiple ranges of a Google Sheet in a single request. More efficient than calling googlesheets_get_values repeatedly when you need several ranges at once.

NameTypeRequiredDescription
rangesarrayrequiredList of A1 notation ranges to fetch values for
spreadsheet_idstringrequiredThe ID of the Google Sheet to read from
major_dimensionstringoptionalWhether values are returned by rows or columns
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
value_render_optionstringoptionalHow values should be rendered in the response
googlesheets_batch_update_values#Update values across multiple ranges of a Google Sheet in a single request. Each entry in the data array specifies its own range and 2D array of values, so you can write to several non-contiguous ranges at once.6 params

Update values across multiple ranges of a Google Sheet in a single request. Each entry in the data array specifies its own range and 2D array of values, so you can write to several non-contiguous ranges at once.

NameTypeRequiredDescription
dataarrayrequiredList of range/values pairs to update. Each object must contain a 'range' (A1 notation string) and a 'values' key (2D array of rows, e.g. [["a","b"],["c","d"]]). Example: [{"range": "Sheet1!A1:B2", "values": [["a","b"],["c","d"]]}]
spreadsheet_idstringrequiredThe ID of the Google Sheet to update
value_input_optionstringrequiredHow input values should be interpreted
include_values_in_responsebooleanoptionalReturn the updated cell values in the response
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_clear_values#Clear all values in a specified range of a Google Sheets spreadsheet. Formatting is preserved; only the cell values are cleared.2 params

Clear all values in a specified range of a Google Sheets spreadsheet. Formatting is preserved; only the cell values are cleared.

NameTypeRequiredDescription
rangestringrequiredThe A1 notation range to clear (e.g. Sheet1!A1:D10)
spreadsheet_idstringrequiredThe ID of the spreadsheet to clear values in
googlesheets_copy_sheet_to#Copy a sheet (tab) from one Google Sheets spreadsheet into another spreadsheet as a new sheet.5 params

Copy a sheet (tab) from one Google Sheets spreadsheet into another spreadsheet as a new sheet.

NameTypeRequiredDescription
destination_spreadsheet_idstringrequiredThe ID of the spreadsheet to copy the sheet into
sheet_idintegerrequiredThe numeric ID of the sheet to copy
spreadsheet_idstringrequiredThe ID of the source spreadsheet containing the sheet to copy
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_create_spreadsheet#Create a new Google Sheets spreadsheet with an optional title and initial sheet configuration. Returns the new spreadsheet ID and metadata.6 params

Create a new Google Sheets spreadsheet with an optional title and initial sheet configuration. Returns the new spreadsheet ID and metadata.

NameTypeRequiredDescription
localestringoptionalLocale of the spreadsheet
schema_versionstringoptionalOptional schema version to use for tool execution
sheetsarrayoptionalInitial sheets to include in the spreadsheet
time_zonestringoptionalTime zone for the spreadsheet
titlestringoptionalTitle of the new spreadsheet
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_delete_dimension#Permanently delete a range of rows or columns from a Google Sheet. Data in the deleted rows or columns is lost and remaining dimensions shift to fill the gap.7 params

Permanently delete a range of rows or columns from a Google Sheet. Data in the deleted rows or columns is lost and remaining dimensions shift to fill the gap.

NameTypeRequiredDescription
dimensionstringrequiredWhether to delete rows or columns
end_indexintegerrequiredThe zero-based end index (exclusive) of the range to delete
sheet_idintegerrequiredThe ID of the sheet (tab) to delete the dimension from
spreadsheet_idstringrequiredThe ID of the Google Sheet to modify
start_indexintegerrequiredThe zero-based start index of the range to delete
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_delete_sheet#Permanently delete a sheet (tab) from a Google Sheets spreadsheet by its sheet ID. This cannot be undone.4 params

Permanently delete a sheet (tab) from a Google Sheets spreadsheet by its sheet ID. This cannot be undone.

NameTypeRequiredDescription
sheet_idintegerrequiredThe numeric ID of the sheet to delete
spreadsheet_idstringrequiredThe ID of the spreadsheet containing the sheet to delete
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_duplicate_sheet#Duplicate an existing sheet (tab) within the same Google Sheets spreadsheet, with an optional new name and insert position.6 params

Duplicate an existing sheet (tab) within the same Google Sheets spreadsheet, with an optional new name and insert position.

NameTypeRequiredDescription
source_sheet_idintegerrequiredThe numeric ID of the sheet to duplicate
spreadsheet_idstringrequiredThe ID of the spreadsheet containing the sheet to duplicate
insert_indexintegeroptionalZero-based position at which to insert the duplicated sheet
new_sheet_namestringoptionalName for the duplicated sheet
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_find_and_replace#Find and replace text within a Google Sheet, either in a specific sheet (tab) or across all sheets in the spreadsheet.10 params

Find and replace text within a Google Sheet, either in a specific sheet (tab) or across all sheets in the spreadsheet.

NameTypeRequiredDescription
findstringrequiredThe text to search for
replacementstringrequiredThe text to replace matches with
spreadsheet_idstringrequiredThe ID of the Google Sheet to modify
include_formulasbooleanoptionalWhether to search within formula text as well as cell values
match_casebooleanoptionalWhether the search should be case-sensitive
match_entire_cellbooleanoptionalWhether the search should match the entire cell contents
schema_versionstringoptionalOptional schema version to use for tool execution
search_by_regexbooleanoptionalWhether the find text should be treated as a regular expression
sheet_idintegeroptionalThe ID of the sheet (tab) to search within. Omit to search all sheets in the spreadsheet
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_format_cells#Apply text and number formatting (bold, italic, font size, number format, horizontal alignment) to a range of cells in a Google Sheet.14 params

Apply text and number formatting (bold, italic, font size, number format, horizontal alignment) to a range of cells in a Google Sheet.

NameTypeRequiredDescription
end_column_indexintegerrequiredThe zero-based end column index (exclusive) of the range
end_row_indexintegerrequiredThe zero-based end row index (exclusive) of the range
sheet_idintegerrequiredThe ID of the sheet (tab) containing the range to format
spreadsheet_idstringrequiredThe ID of the Google Sheet to modify
start_column_indexintegerrequiredThe zero-based start column index of the range
start_row_indexintegerrequiredThe zero-based start row index of the range
boldbooleanoptionalWhether text in the range should be bold
font_sizeintegeroptionalFont size in points to apply to the range
horizontal_alignmentstringoptionalHorizontal alignment of text in the range
italicbooleanoptionalWhether text in the range should be italic
number_format_patternstringoptionalCustom number format pattern to apply (used with number_format_type)
number_format_typestringoptionalThe type of number format to apply to the range
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_freeze_panes#Freeze a number of rows and/or columns at the top or left of a Google Sheet so they stay visible while scrolling.6 params

Freeze a number of rows and/or columns at the top or left of a Google Sheet so they stay visible while scrolling.

NameTypeRequiredDescription
sheet_idintegerrequiredThe ID of the sheet (tab) to freeze panes on
spreadsheet_idstringrequiredThe ID of the Google Sheet to modify
frozen_column_countintegeroptionalNumber of columns to freeze starting from the left
frozen_row_countintegeroptionalNumber of rows to freeze starting from the top
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_get_values#Returns only the cell values from a specific range in a Google Sheet — no metadata, no formatting, just the data. For full spreadsheet metadata and formatting, use googlesheets_read_spreadsheet instead.6 params

Returns only the cell values from a specific range in a Google Sheet — no metadata, no formatting, just the data. For full spreadsheet metadata and formatting, use googlesheets_read_spreadsheet instead.

NameTypeRequiredDescription
rangestringrequiredCell range to read in A1 notation
spreadsheet_idstringrequiredThe ID of the Google Sheet
major_dimensionstringoptionalWhether values are returned by rows or columns
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
value_render_optionstringoptionalHow values should be rendered in the response
googlesheets_insert_dimension#Insert new rows or columns into a Google Sheet at a specific position. Existing rows or columns are shifted to make room for the new ones.8 params

Insert new rows or columns into a Google Sheet at a specific position. Existing rows or columns are shifted to make room for the new ones.

NameTypeRequiredDescription
dimensionstringrequiredWhether to insert rows or columns
end_indexintegerrequiredThe zero-based end index (exclusive) of the range to insert
sheet_idintegerrequiredThe ID of the sheet (tab) to insert the dimension into
spreadsheet_idstringrequiredThe ID of the Google Sheet to modify
start_indexintegerrequiredThe zero-based start index of the range to insert
inherit_from_beforebooleanoptionalWhether new rows/columns should inherit properties from the dimension before them
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_merge_cells#Merge a range of cells in a Google Sheet into a single cell, merging all cells, only columns, or only rows within the range.9 params

Merge a range of cells in a Google Sheet into a single cell, merging all cells, only columns, or only rows within the range.

NameTypeRequiredDescription
end_column_indexintegerrequiredThe zero-based end column index (exclusive) of the range
end_row_indexintegerrequiredThe zero-based end row index (exclusive) of the range
sheet_idintegerrequiredThe ID of the sheet (tab) containing the range to merge
spreadsheet_idstringrequiredThe ID of the Google Sheet to modify
start_column_indexintegerrequiredThe zero-based start column index of the range
start_row_indexintegerrequiredThe zero-based start row index of the range
merge_typestringoptionalHow the range should be merged
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_read_spreadsheet#Returns everything about a spreadsheet — including spreadsheet metadata, sheet properties, cell values, formatting, themes, and pixel sizes. If you only need cell values, use googlesheets_get_values instead.5 params

Returns everything about a spreadsheet — including spreadsheet metadata, sheet properties, cell values, formatting, themes, and pixel sizes. If you only need cell values, use googlesheets_get_values instead.

NameTypeRequiredDescription
spreadsheet_idstringrequiredThe ID of the Google Sheet to read
include_grid_databooleanoptionalInclude cell data in the response
rangesstringoptionalCell range to read in A1 notation
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_rename_sheet#Rename an existing sheet (tab) within a Google Sheets spreadsheet.5 params

Rename an existing sheet (tab) within a Google Sheets spreadsheet.

NameTypeRequiredDescription
sheet_idintegerrequiredThe numeric ID of the sheet to rename
spreadsheet_idstringrequiredThe ID of the spreadsheet containing the sheet to rename
titlestringrequiredNew title for the sheet
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
googlesheets_update_values#Update cell values in a specific range of a Google Sheet. Supports writing single cells or multiple rows and columns at once.7 params

Update cell values in a specific range of a Google Sheet. Supports writing single cells or multiple rows and columns at once.

NameTypeRequiredDescription
rangestringrequiredCell range to update in A1 notation
spreadsheet_idstringrequiredThe ID of the Google Sheet to update
valuesarrayrequired2D array of values to write to the range
include_values_in_responsebooleanoptionalReturn the updated cell values in the response
schema_versionstringoptionalOptional schema version to use for tool execution
tool_versionstringoptionalOptional tool version to use for execution
value_input_optionstringoptionalHow input values should be interpreted