BigQuery (Service Account) connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

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. Set up the connector

   Register your BigQuery (Service Account) credentials with Scalekit so it handles the token lifecycle. You do this once per environment.

   Dashboard setup steps

   In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find BigQuery (Service Account) and click Create.

   That’s it — no OAuth credentials or redirect URIs needed. BigQuery Service Account uses server-to-server authentication handled entirely through your GCP service account credentials.

What you can do

Connect this agent connector to let your agent:

• Query insert — Submit an asynchronous BigQuery query job
• Job cancel — Request cancellation of a running BigQuery job
• Run dry, query — Validate a SQL query and estimate its cost without executing it
• List tables, table data, routines — List all tables and views in a BigQuery dataset
• Get table, routine, query results — Retrieve metadata and schema for a specific BigQuery table or view, including column names, types, descriptions, and table properties

Common workflows

Execute a tool

Node.js

const result = await actions.executeTool({
  connector: 'bigqueryserviceaccount',
  identifier: 'user_123',
  toolName: 'bigqueryserviceaccount_run_query',
  toolInput: {
    query: 'SELECT 1 AS test',
  },
});
console.log(result);

Python

result = actions.execute_tool(
    connection_name='bigqueryserviceaccount',
    identifier='user_123',
    tool_name='bigqueryserviceaccount_run_query',
    tool_input={
        "query": "SELECT 1 AS test",
    },
)
print("Query result:", result.data)

Proxy API call

Project ID is resolved automatically

Scalekit automatically resolves the GCP project ID in the base URL from the connected service account credentials. You only need to provide the path relative to the project, e.g. /datasets or /datasets/{datasetId}/tables.

Node.js

const result = await actions.request({
  connectionName: 'bigqueryserviceaccount',
  identifier: 'user_123',
  path: '/datasets',
  method: 'GET',
});
console.log(result);

Python

result = actions.request(
    connection_name='bigqueryserviceaccount',
    identifier='user_123',
    path="/datasets",
    method="GET",
)
print(result)

Tool list

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.

bigqueryserviceaccount_cancel_job#Request cancellation of a running BigQuery job. Returns the final job resource. Cancellation is best-effort and the job may complete before it can be cancelled.2 params▾

Request cancellation of a running BigQuery job. Returns the final job resource. Cancellation is best-effort and the job may complete before it can be cancelled.

NameTypeRequiredDescription

job_idstringrequiredThe ID of the job to cancel

locationstringoptionalGeographic location where the job was created, e.g. US or EU

bigqueryserviceaccount_dry_run_query#Validate a SQL query and estimate its cost without executing it. Returns statistics.totalBytesProcessed so you can check byte usage before running the real job.3 params▾

Validate a SQL query and estimate its cost without executing it. Returns statistics.totalBytesProcessed so you can check byte usage before running the real job.

NameTypeRequiredDescription

querystringrequiredSQL query to validate and estimate

locationstringoptionalGeographic location where the job should run, e.g. US or EU

use_legacy_sqlbooleanoptionalUse BigQuery legacy SQL syntax instead of standard SQL

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

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

NameTypeRequiredDescription

dataset_idstringrequiredThe ID of the dataset to retrieve

bigqueryserviceaccount_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.2 params▾

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.

NameTypeRequiredDescription

job_idstringrequiredThe ID of the job to retrieve

locationstringoptionalGeographic location where the job was created, e.g. US or EU

bigqueryserviceaccount_get_model#Retrieve metadata for a specific BigQuery ML model, including model type, feature columns, label columns, and training run details.2 params▾

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

NameTypeRequiredDescription

dataset_idstringrequiredThe ID of the dataset containing the model

model_idstringrequiredThe ID of the model to retrieve

bigqueryserviceaccount_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.5 params▾

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

NameTypeRequiredDescription

job_idstringrequiredThe ID of the completed query job

locationstringoptionalGeographic location where the job was created, e.g. US or EU

max_resultsintegeroptionalMaximum number of rows to return per page

page_tokenstringoptionalPage token from a previous response to retrieve the next page of results

timeout_msintegeroptionalMaximum milliseconds to wait if the query has not yet completed

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

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

NameTypeRequiredDescription

dataset_idstringrequiredThe ID of the dataset containing the routine

routine_idstringrequiredThe ID of the routine to retrieve

bigqueryserviceaccount_get_table#Retrieve metadata and schema for a specific BigQuery table or view, including column names, types, descriptions, and table properties.2 params▾

Retrieve metadata and schema for a specific BigQuery table or view, including column names, types, descriptions, and table properties.

NameTypeRequiredDescription

dataset_idstringrequiredThe ID of the dataset containing the table

table_idstringrequiredThe ID of the table or view to retrieve

bigqueryserviceaccount_insert_query_job#Submit an asynchronous BigQuery query job. Returns a job ID that can be used with Get Job or Get Query Results to poll for completion and retrieve results.9 params▾

Submit an asynchronous BigQuery query job. Returns a job ID that can be used with Get Job or Get Query Results to poll for completion and retrieve results.

NameTypeRequiredDescription

querystringrequiredSQL query to execute

create_dispositionstringoptionalSpecifies whether the destination table is created if it does not exist

destination_dataset_idstringoptionalDataset ID to write query results into

destination_table_idstringoptionalTable ID to write query results into

locationstringoptionalGeographic location where the job should run, e.g. US or EU

maximum_bytes_billedstringoptionalMaximum bytes that can be billed for this query; query fails if limit is exceeded

prioritystringoptionalJob priority: INTERACTIVE (default) or BATCH

use_legacy_sqlbooleanoptionalUse BigQuery legacy SQL syntax instead of standard SQL

write_dispositionstringoptionalSpecifies the action when the destination table already exists

bigqueryserviceaccount_list_datasets#List all BigQuery datasets in the project. Supports filtering by label and pagination.4 params▾

List all BigQuery datasets in the project. Supports filtering by label and pagination.

NameTypeRequiredDescription

allbooleanoptionalIf true, includes hidden datasets in the results

filterstringoptionalLabel filter expression to restrict results, e.g. labels.env:prod

max_resultsintegeroptionalMaximum number of datasets to return per page

page_tokenstringoptionalPage token from a previous response to retrieve the next page

bigqueryserviceaccount_list_jobs#List BigQuery jobs in the project. Supports filtering by state and projection, and pagination.5 params▾

List BigQuery jobs in the project. Supports filtering by state and projection, and pagination.

NameTypeRequiredDescription

all_usersbooleanoptionalIf true, returns jobs for all users in the project; otherwise returns only the current user's jobs

max_resultsintegeroptionalMaximum number of jobs to return per page

page_tokenstringoptionalPage token from a previous response to retrieve the next page

projectionstringoptionalControls the fields returned: minimal (default) or full

state_filterstringoptionalFilter jobs by state: done, pending, or running

bigqueryserviceaccount_list_models#List all BigQuery ML models in a dataset, including their model type, training status, and creation time.3 params▾

List all BigQuery ML models in a dataset, including their model type, training status, and creation time.

NameTypeRequiredDescription

dataset_idstringrequiredThe ID of the dataset to list models from

max_resultsintegeroptionalMaximum number of models to return per page

page_tokenstringoptionalPage token from a previous response to retrieve the next page

bigqueryserviceaccount_list_routines#List all stored procedures and user-defined functions (UDFs) in a BigQuery dataset.4 params▾

List all stored procedures and user-defined functions (UDFs) in a BigQuery dataset.

NameTypeRequiredDescription

dataset_idstringrequiredThe ID of the dataset to list routines from

filterstringoptionalFilter expression to restrict results, e.g. routineType:SCALAR_FUNCTION

max_resultsintegeroptionalMaximum number of routines to return per page

page_tokenstringoptionalPage token from a previous response to retrieve the next page

bigqueryserviceaccount_list_table_data#Read rows directly from a BigQuery table without writing a SQL query. Supports pagination, row offset, and field selection.6 params▾

Read rows directly from a BigQuery table without writing a SQL query. Supports pagination, row offset, and field selection.

NameTypeRequiredDescription

dataset_idstringrequiredThe ID of the dataset containing the table

table_idstringrequiredThe ID of the table to read rows from

max_resultsintegeroptionalMaximum number of rows to return per page

page_tokenstringoptionalPage token from a previous response to retrieve the next page

selected_fieldsstringoptionalComma-separated list of fields to return; if omitted all fields are returned

start_indexintegeroptionalZero-based row index to start reading from

bigqueryserviceaccount_list_tables#List all tables and views in a BigQuery dataset. Supports pagination.3 params▾

List all tables and views in a BigQuery dataset. Supports pagination.

NameTypeRequiredDescription

dataset_idstringrequiredThe ID of the dataset to list tables from

max_resultsintegeroptionalMaximum number of tables to return per page

page_tokenstringoptionalPage token from a previous response to retrieve the next page

bigqueryserviceaccount_run_query#Execute a SQL query synchronously against BigQuery and return results immediately. Best for short-running queries. For long-running queries use Insert Query Job instead.7 params▾

Execute a SQL query synchronously against BigQuery and return results immediately. Best for short-running queries. For long-running queries use Insert Query Job instead.

NameTypeRequiredDescription

querystringrequiredSQL query to execute

create_sessionbooleanoptionalIf true, creates a new session and returns a session ID in the response

dry_runbooleanoptionalIf true, validates the query and returns estimated bytes processed without executing

locationstringoptionalGeographic location of the dataset, e.g. US or EU

max_resultsintegeroptionalMaximum number of rows to return in the response

timeout_msintegeroptionalMaximum milliseconds to wait for query completion before returning

use_legacy_sqlbooleanoptionalUse BigQuery legacy SQL syntax instead of standard SQL