> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation. > > - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install @scalekit-auth-stack` > - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install @scalekit-auth-stack` > - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `` > - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill ` > > `` / ``: `agentkit`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # BigQuery (Service Account) connector Connect to Google BigQuery using a GCP service account for server-to-server authentication without user login. **Authentication:** Service Account **Categories:** Data, Analytics 1. ### Install the SDK ### Node.js ```bash frame="terminal" npm install @scalekit-sdk/node ``` ### Python ```bash frame="terminal" pip install scalekit ``` Full SDK reference: [Node.js](/agentkit/sdks/node/) | [Python](/agentkit/sdks/python/) 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh showLineNumbers=false title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_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](https://app.scalekit.com), 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 export const sectionTitle = 'Common workflows' ## Execute a tool ### Node.js ```typescript const result = await actions.executeTool({ connector: 'bigqueryserviceaccount', identifier: 'user_123', toolName: 'bigqueryserviceaccount_run_query', toolInput: { query: 'SELECT 1 AS test', }, }); console.log(result); ``` ### Python ```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 > tip: 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 ```typescript const result = await actions.request({ connectionName: 'bigqueryserviceaccount', identifier: 'user_123', path: '/datasets', method: 'GET', }); console.log(result); ``` ### Python ```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. ## Tool list ### `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. Parameters: - `job_id` (`string`, required): The ID of the job to cancel - `location` (`string`, optional): Geographic 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. Parameters: - `query` (`string`, required): SQL query to validate and estimate - `location` (`string`, optional): Geographic location where the job should run, e.g. US or EU - `use_legacy_sql` (`boolean`, optional): Use 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. Parameters: - `dataset_id` (`string`, required): The 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. Parameters: - `job_id` (`string`, required): The ID of the job to retrieve - `location` (`string`, optional): Geographic 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. Parameters: - `dataset_id` (`string`, required): The ID of the dataset containing the model - `model_id` (`string`, required): The 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. Parameters: - `job_id` (`string`, required): The ID of the completed query job - `location` (`string`, optional): Geographic location where the job was created, e.g. US or EU - `max_results` (`integer`, optional): Maximum number of rows to return per page - `page_token` (`string`, optional): Page token from a previous response to retrieve the next page of results - `timeout_ms` (`integer`, optional): Maximum 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. Parameters: - `dataset_id` (`string`, required): The ID of the dataset containing the routine - `routine_id` (`string`, required): The 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. Parameters: - `dataset_id` (`string`, required): The ID of the dataset containing the table - `table_id` (`string`, required): The 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. Parameters: - `query` (`string`, required): SQL query to execute - `create_disposition` (`string`, optional): Specifies whether the destination table is created if it does not exist - `destination_dataset_id` (`string`, optional): Dataset ID to write query results into - `destination_table_id` (`string`, optional): Table ID to write query results into - `location` (`string`, optional): Geographic location where the job should run, e.g. US or EU - `maximum_bytes_billed` (`string`, optional): Maximum bytes that can be billed for this query; query fails if limit is exceeded - `priority` (`string`, optional): Job priority: INTERACTIVE (default) or BATCH - `use_legacy_sql` (`boolean`, optional): Use BigQuery legacy SQL syntax instead of standard SQL - `write_disposition` (`string`, optional): Specifies the action when the destination table already exists ### `bigqueryserviceaccount_list_datasets` List all BigQuery datasets in the project. Supports filtering by label and pagination. Parameters: - `all` (`boolean`, optional): If true, includes hidden datasets in the results - `filter` (`string`, optional): Label filter expression to restrict results, e.g. labels.env:prod - `max_results` (`integer`, optional): Maximum number of datasets to return per page - `page_token` (`string`, optional): Page 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. Parameters: - `all_users` (`boolean`, optional): If true, returns jobs for all users in the project; otherwise returns only the current user's jobs - `max_results` (`integer`, optional): Maximum number of jobs to return per page - `page_token` (`string`, optional): Page token from a previous response to retrieve the next page - `projection` (`string`, optional): Controls the fields returned: minimal (default) or full - `state_filter` (`string`, optional): Filter 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. Parameters: - `dataset_id` (`string`, required): The ID of the dataset to list models from - `max_results` (`integer`, optional): Maximum number of models to return per page - `page_token` (`string`, optional): Page 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. Parameters: - `dataset_id` (`string`, required): The ID of the dataset to list routines from - `filter` (`string`, optional): Filter expression to restrict results, e.g. routineType:SCALAR_FUNCTION - `max_results` (`integer`, optional): Maximum number of routines to return per page - `page_token` (`string`, optional): Page 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. Parameters: - `dataset_id` (`string`, required): The ID of the dataset containing the table - `table_id` (`string`, required): The ID of the table to read rows from - `max_results` (`integer`, optional): Maximum number of rows to return per page - `page_token` (`string`, optional): Page token from a previous response to retrieve the next page - `selected_fields` (`string`, optional): Comma-separated list of fields to return; if omitted all fields are returned - `start_index` (`integer`, optional): Zero-based row index to start reading from ### `bigqueryserviceaccount_list_tables` List all tables and views in a BigQuery dataset. Supports pagination. Parameters: - `dataset_id` (`string`, required): The ID of the dataset to list tables from - `max_results` (`integer`, optional): Maximum number of tables to return per page - `page_token` (`string`, optional): Page 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. Parameters: - `query` (`string`, required): SQL query to execute - `create_session` (`boolean`, optional): If true, creates a new session and returns a session ID in the response - `dry_run` (`boolean`, optional): If true, validates the query and returns estimated bytes processed without executing - `location` (`string`, optional): Geographic location of the dataset, e.g. US or EU - `max_results` (`integer`, optional): Maximum number of rows to return in the response - `timeout_ms` (`integer`, optional): Maximum milliseconds to wait for query completion before returning - `use_legacy_sql` (`boolean`, optional): Use BigQuery legacy SQL syntax instead of standard SQL --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |