Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Google BigQuery

Scalekit connector
Open markdown

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

Tools
47
What they doRead · write · destructive
23 · 17 · 723 read17 write7 destructive
Users sign in with
OAuth app
Your own Google app

What you can do

  • Run SQL queries: execute queries directly or as background jobs, then check status and page through results
  • Explore datasets and tables: list projects, datasets, and tables, and read table schemas and rows without writing SQL
  • Manage datasets and tables: create, update, delete, and restore datasets, and create, change, or delete tables and views
  • Load and copy data: stream rows into tables and run load, copy, and export jobs
  • Manage routines and models: create, update, and delete stored procedures and functions, and inspect or update ML models
  • Control access: set access policies on tables and routines, and add row access policies that limit which rows users see

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 BigQuery connection

    In AgentKit > Connections, create a Google BigQuery 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 BigQuery 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 BigQuery connection.

    Console steps with screenshots

    Register your Scalekit environment with the Google BigQuery 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 BigQuery 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 BigQuery API

      • In Google Cloud Console, go to APIs & Services → Library. Search for “BigQuery 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 = 'bigquery'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Google BigQuery:', 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: 'bigquery_list_projects',
      toolInput: {},
    })
    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
  • bigquery_get_datasetRetrieve metadata for a specific BigQuery dataset, including location, description, labels, access controls, and creation/modification times.Read-only

    Get Dataset

    Retrieve metadata for a specific BigQuery dataset, including location, description, labels, access controls, and creation/modification times.

    Inputs

    dataset_idstringrequired
    The ID of the dataset to retrieve
    project_idstringrequired
    The Google Cloud project ID that owns this BigQuery resource.
  • bigquery_get_jobRetrieve the status and configuration of a BigQuery job by its job ID.Read-only

    Get Job

    Retrieve the status and configuration of a BigQuery job by its job ID. Use this to poll for completion of an async query job submitted via Insert Query Job.

    Inputs

    job_idstringrequired
    The ID of the job to retrieve
    project_idstringrequired
    The Google Cloud project ID that owns this BigQuery resource.
    locationstring
    Geographic location where the job was created, e.g. US or EU
  • bigquery_get_modelRetrieve metadata for a specific BigQuery ML model, including model type, feature columns, label columns, and training run details.Read-only

    Get Model

    Retrieve metadata for a specific BigQuery ML model, including model type, feature columns, label columns, and training run details.

    Inputs

    dataset_idstringrequired
    The ID of the dataset containing the model
    model_idstringrequired
    The ID of the model to retrieve
    project_idstringrequired
    The Google Cloud project ID that owns this BigQuery resource.
  • bigquery_get_query_resultsRetrieve the results of a completed BigQuery query job.Read-only

    Get Query Results

    Retrieve the results of a completed BigQuery query job. Supports pagination via page tokens. Use after polling Get Job until status is DONE.

    Inputs

    job_idstringrequired
    The ID of the completed query job
    project_idstringrequired
    The Google Cloud project ID that owns this BigQuery resource.
    locationstring
    Geographic location where the job was created, e.g. US or EU
    max_resultsinteger
    Maximum number of rows to return per page
    page_tokenstring
    Page token from a previous response to retrieve the next page of results
    timeout_msinteger
    Maximum milliseconds to wait if the query has not yet completed
  • bigquery_get_routineRetrieve the definition and metadata of a specific BigQuery routine (stored procedure or UDF), including its arguments, return type, and body.Read-only

    Get Routine

    Retrieve the definition and metadata of a specific BigQuery routine (stored procedure or UDF), including its arguments, return type, and body.

    Inputs

    dataset_idstringrequired
    The ID of the dataset containing the routine
    project_idstringrequired
    The Google Cloud project ID that owns this BigQuery resource.
    routine_idstringrequired
    The ID of the routine to retrieve
  • bigquery_get_routine_iam_policyRetrieve the IAM access control policy currently set on a BigQuery routine (stored procedure or UDF).Read-only

    Get Routine IAM Policy

    Retrieve the IAM access control policy currently set on a BigQuery routine (stored procedure or UDF).

    Inputs

    dataset_idstringrequired
    The ID of the dataset containing the routine
    project_idstringrequired
    The Google Cloud project ID that owns this BigQuery resource.
    routine_idstringrequired
    The ID of the routine to fetch the IAM policy for
    requested_policy_versioninteger
    The policy format version to be returned
  • bigquery_get_row_access_policyRetrieve the definition of a single row access policy on a BigQuery table.Read-only

    Get Row Access Policy

    Retrieve the definition of a single row access policy on a BigQuery table.

    Inputs

    dataset_idstringrequired
    The ID of the dataset containing the table
    project_idstringrequired
    The Google Cloud project ID that owns this BigQuery resource.
    row_access_policy_idstringrequired
    The ID of the row access policy to retrieve
    table_idstringrequired
    The ID of the table containing the row access policy
  • bigquery_get_row_access_policy_iam_policyRetrieve the IAM policy for a row access policy on a BigQuery table.Read-only

    Get Row Access Policy IAM Policy

    Retrieve the IAM policy for a row access policy on a BigQuery table.

    Inputs

    dataset_idstringrequired
    The ID of the dataset containing the table
    project_idstringrequired
    The Google Cloud project ID that owns this BigQuery resource.
    row_access_policy_idstringrequired
    The ID of the row access policy to get the IAM policy for
    table_idstringrequired
    The ID of the table containing the row access policy
    requested_policy_versioninteger
    The IAM policy format version to be returned

Workflows

Proxy API call
const result = await actions.request({
  connectionName: 'bigquery',
  identifier: 'user_123',
  path: '/bigquery/v2/projects',
  method: 'GET',
});
console.log(result);
Execute a tool
const result = await actions.executeTool({
  connector: 'bigquery',
  identifier: 'user_123',
  toolName: 'bigquery_list_projects',
  toolInput: {},
});
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.

Related: other Analytics connectors

All 109 in Analytics