Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Google Sheets

Scalekit connector
Open markdown

The Google Sheets connector lets your AI agent act in each user's Google Sheets account. Each user signs in to Google Sheets once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 48 tools.

Tools
48
What they doRead · write · destructive
7 · 29 · 127 read29 write12 destructive
Users sign in with
OAuth app
Your own Google app

What you can do

  • Read spreadsheets: fetch cell values from one or more ranges, or full spreadsheet metadata and formatting
  • Write and append data: update cells across ranges, append rows, clear values, and find and replace text
  • Create and organize sheets: create spreadsheets, and add, duplicate, rename, copy, and delete tabs
  • Restructure rows and columns: insert, move, resize, hide, and delete rows, columns, and cell ranges
  • Format cells: apply number and text formatting, alternating colors, conditional rules, merges, and frozen panes
  • Sort, filter, and chart: sort ranges, set filters, protect ranges, and add charts built from source data

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    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. Create the Google Sheets connection

    In AgentKit > Connections, create a Google Sheets connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register a Google OAuth app

    Google Sheets connections use your own OAuth app. Register one with Google and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Google Sheets connection.

    Console steps with screenshots

    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 Console → APIs & Services → Credentials. 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 & Services → Library. 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.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_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)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'googlesheets_read_spreadsheet',
      toolInput: { spreadsheet_id: 'YOUR_SPREADSHEET_ID' },
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • googlesheets_batch_get_valuesReturn cell values for multiple ranges of a Google Sheet in a single request.Read-only

    Batch Get Sheet 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.

    Inputs

    rangesarrayrequired
    List of A1 notation ranges to fetch values for
    spreadsheet_idstringrequired
    The ID of the Google Sheet to read from
    major_dimensionstring
    Whether values are returned by rows or columnsone of ROWSCOLUMNSdefault ROWS
    value_render_optionstring
    How values should be rendered in the responseone of FORMATTED_VALUEUNFORMATTED_VALUEFORMULAdefault FORMATTED_VALUE

    Also accepts schema_version and tool_version to pin a version.

  • googlesheets_batch_get_values_by_data_filterReturn cell values for one or more ranges of a Google Sheet, selected by DataFilter (an A1 range, a GridRange, or a developer metadata lookup) instead of a plain A1 string.Read-only

    Batch Get Values by Data Filter

    Return cell values for one or more ranges of a Google Sheet, selected by DataFilter (an A1 range, a GridRange, or a developer metadata lookup) instead of a plain A1 string. Use this instead of googlesheets_batch_get_values when you need to select ranges by developer metadata or a structured GridRange.

    Inputs

    data_filtersarrayrequired
    List of DataFilter objects selecting which ranges to fetch values for. Each object must set exactly one of 'a1Range' (string), 'gridRange' (object), or 'developerMetadataLookup' (object).
    spreadsheet_idstringrequired
    The ID of the Google Sheet to read from
    date_time_render_optionstring
    How dates, times, and durations should be represented in the responseone of SERIAL_NUMBERFORMATTED_STRINGdefault SERIAL_NUMBER
    major_dimensionstring
    Whether values are returned by rows or columnsone of ROWSCOLUMNSdefault ROWS
    value_render_optionstring
    How values should be rendered in the responseone of FORMATTED_VALUEUNFORMATTED_VALUEFORMULAdefault FORMATTED_VALUE

    Also accepts schema_version and tool_version to pin a version.

  • googlesheets_get_developer_metadataRetrieve a single developer metadata entry from a Google Sheet by its metadata ID.Read-only

    Get Developer Metadata

    Retrieve a single developer metadata entry from a Google Sheet by its metadata ID. Developer metadata lets apps attach hidden key-value data to a spreadsheet, sheet, row, or column.

    Inputs

    metadata_idintegerrequired
    The spreadsheet-scoped ID of the developer metadata entry to retrieve.
    spreadsheet_idstringrequired
    The ID of the Google Sheet to read from
  • googlesheets_get_spreadsheet_by_data_filterReturn spreadsheet metadata and (optionally) cell data for only the ranges that match one or more DataFilters (an A1 range, a GridRange, or a developer metadata lookup).Read-only

    Get Spreadsheet by Data Filter

    Return spreadsheet metadata and (optionally) cell data for only the ranges that match one or more DataFilters (an A1 range, a GridRange, or a developer metadata lookup). Use this instead of googlesheets_read_spreadsheet when you need to select ranges by developer metadata or a structured GridRange rather than a plain A1 string.

    Inputs

    data_filtersarrayrequired
    List of DataFilter objects selecting which parts of the spreadsheet to return. Each object must set exactly one of 'a1Range' (string), 'gridRange' (object), or 'developerMetadataLookup' (object).
    spreadsheet_idstringrequired
    The ID of the Google Sheet to read from
    include_grid_databoolean
    Include cell data in the responsedefault true

    Also accepts schema_version and tool_version to pin a version.

  • googlesheets_get_valuesReturns only the cell values from a specific range in a Google Sheet — no metadata, no formatting, just the data.Read-only

    Get Sheet 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.

    Inputs

    rangestringrequired
    Cell range to read in A1 notation
    spreadsheet_idstringrequired
    The ID of the Google Sheet
    major_dimensionstring
    Whether values are returned by rows or columnsone of ROWSCOLUMNSdefault ROWS
    value_render_optionstring
    How values should be rendered in the responseone of FORMATTED_VALUEUNFORMATTED_VALUEFORMULAdefault FORMATTED_VALUE

    Also accepts schema_version and tool_version to pin a version.

  • googlesheets_read_spreadsheetReturns everything about a spreadsheet — including spreadsheet metadata, sheet properties, cell values, formatting, themes, and pixel sizes.Read-only

    Read Google Sheet

    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.

    Inputs

    spreadsheet_idstringrequired
    The ID of the Google Sheet to read
    include_grid_databoolean
    Include cell data in the responsedefault true
    rangesstring
    Cell range to read in A1 notation

    Also accepts schema_version and tool_version to pin a version.

  • googlesheets_search_developer_metadataSearch for developer metadata entries in a Google Sheet by key, or by the sheet/row/column they are attached to.Read-only

    Search Developer Metadata

    Search for developer metadata entries in a Google Sheet by key, or by the sheet/row/column they are attached to. Returns all matching entries with their location and value.

    Inputs

    metadata_keystringrequired
    Only return developer metadata entries with this exact key.
    spreadsheet_idstringrequired
    The ID of the Google Sheet to search
  • googlesheets_add_bandingApply alternating row colors (banding) to a range in a Google Sheet, using explicit hex colors for the two alternating bands and an optional header row color.Write

    Add Banded Range

    Apply alternating row colors (banding) to a range in a Google Sheet, using explicit hex colors for the two alternating bands and an optional header row color.

    Inputs

    end_column_indexintegerrequired
    Zero-based end column index of the range (exclusive).
    end_row_indexintegerrequired
    Zero-based end row index of the range (exclusive).
    first_band_color_hexstringrequired
    Hex color for odd-numbered rows in the band.
    second_band_color_hexstringrequired
    Hex color for even-numbered rows in the band.
    sheet_idintegerrequired
    The ID of the sheet (tab) containing the range to band.
    spreadsheet_idstringrequired
    The ID of the Google Sheet to modify
    start_column_indexintegerrequired
    Zero-based start column index of the range (inclusive).
    start_row_indexintegerrequired
    Zero-based start row index of the range (inclusive).
    header_color_hexstring
    Optional hex color for the first (header) row of the range, drawn distinct from the alternating bands.

Workflows

Proxy API call
const result = await actions.request({
  connectionName: 'googlesheets',
  identifier: 'user_123',
  path: '/v4/spreadsheets',
  method: 'GET',
});
console.log(result);
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.

All 41 in Files & Documents