A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The BigQuery API is how an app or AI agent works with a BigQuery data warehouse: running a SQL query, streaming new rows into a table, creating or deleting a dataset, or reading a table's rows directly. Access is granted through an OAuth 2.0 access token whose scopes set the broad category of access, while the identity's IAM roles set which projects, datasets, and tables a call can reach. BigQuery does not push events, so an app learns about a finished job by polling it and about new data by querying.
How an app or AI agent connects to BigQuery determines what it can reach. There is a REST API for running jobs and managing datasets and tables, and a hosted server that exposes BigQuery tools to agents, and each is governed by the credential behind it and the permissions that credential carries.
The REST API takes JSON request bodies, returns JSON, and pages through lists with a page token, at https://bigquery.googleapis.com/bigquery/v2 (the older host https://www.googleapis.com/bigquery/v2 still resolves). A call authenticates with an OAuth 2.0 access token in the Authorization header, minted for a user or a service account. The token's scopes plus the caller's IAM roles together decide which projects, datasets, and methods the call can reach.
A fully managed, remote Model Context Protocol server at https://bigquery.googleapis.com/mcp exposes BigQuery tools to AI agents and LLM clients, and is enabled when the BigQuery API is enabled. It authenticates with OAuth 2.0 and authorizes with IAM, not API keys, and its tools cover list_dataset_ids, get_dataset_info, list_table_ids, get_table_info, and execute_sql, with a read-only variant for queries. Results are capped (3,000 rows by default), and it was in preview as of January 2026.
A person signs in and consents to a set of scopes, and the resulting access token acts as that person, limited to both the granted scopes and that person's IAM roles. A refresh token keeps long-running access alive. This is the route for an integration acting on behalf of a human.
A service account is a non-human identity with its own IAM roles. Its credentials are exchanged for a short-lived OAuth 2.0 access token, which authenticates server-to-server calls without a person present. The account reaches only the projects and datasets its IAM roles allow.
The BigQuery API is split into areas an agent can act on, like jobs that run queries, the datasets and tables that hold data, the rows streamed into a table, and the routines and models defined inside a dataset. Each area has its own methods, and a write in some of them runs SQL, changes a schema, or deletes data.
Methods for running and managing jobs, including queries, loads, exports, and copies.
Methods for working with datasets, the containers that hold tables, routines, and models.
Methods for working with tables and their schemas.
Methods for streaming rows into a table and reading rows back out.
Methods for working with routines, the stored functions and procedures defined in a dataset.
Methods for working with machine-learning models trained inside a dataset.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Jobs (queries & loads)Methods for running and managing jobs, including queries, loads, exports, and copies.7 | ||||||
| POST | /projects/{projectId}/queries | Run a SQL query and return its results, starting a query job synchronously. | write | bigquery | Current | |
Needs https://www.googleapis.com/auth/bigquery or cloud-platform. A SELECT is read-only, but the same method can run DML and DDL that change or delete data, so it is classed as a write. Acts onjob Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /projects/{projectId}/jobs | Start a job: a query, load, export, or copy. | write | bigquery | Current | |
Needs https://www.googleapis.com/auth/bigquery or cloud-platform. A load job that reads from Cloud Storage also needs a storage read scope. Acts onjob Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{projectId}/jobs/{jobId} | Retrieve a job, including its status, used to poll whether a query has finished. | read | bigquery.readonly | Current | |
Read-only. https://www.googleapis.com/auth/bigquery.readonly is enough. Acts onjob Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{projectId}/queries/{jobId} | Retrieve the results of a query job, with paging for large result sets. | read | bigquery.readonly | Current | |
Read-only. https://www.googleapis.com/auth/bigquery.readonly is enough. Acts onjob Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{projectId}/jobs | List the jobs started in a project. | read | bigquery.readonly | Current | |
Read-only. Returns jobs visible to the calling identity. Acts onjob Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /projects/{projectId}/jobs/{jobId}/cancel | Request cancellation of a running job. | write | bigquery | Current | |
Needs https://www.googleapis.com/auth/bigquery or cloud-platform. Cancellation is best-effort and may not stop a job already finishing. Acts onjob Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /projects/{projectId}/jobs/{jobId} | Delete the metadata of a finished job. | write | bigquery | Current | |
Removes the job record; it does not undo the work the job did. Acts onjob Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DatasetsMethods for working with datasets, the containers that hold tables, routines, and models.6 | ||||||
| GET | /projects/{projectId}/datasets | List the datasets in a project. | read | bigquery.readonly | Current | |
Read-only. https://www.googleapis.com/auth/bigquery.readonly is enough. Acts ondataset Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{projectId}/datasets/{datasetId} | Retrieve a dataset and its metadata, including access controls. | read | bigquery.readonly | Current | |
Read-only. The access list it returns names who can reach the dataset. Acts ondataset Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /projects/{projectId}/datasets | Create a new dataset in a project. | write | bigquery | Current | |
Needs https://www.googleapis.com/auth/bigquery or cloud-platform. Acts ondataset Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /projects/{projectId}/datasets/{datasetId} | Update parts of a dataset, including its access list, by partial replacement. | write | bigquery | Current | |
Editing the access list changes who can reach the dataset and its tables. Acts ondataset Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /projects/{projectId}/datasets/{datasetId} | Replace a dataset's metadata in full. | write | bigquery | Current | |
Unlike patch, this overwrites the whole resource, so any field left out is cleared. Acts ondataset Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /projects/{projectId}/datasets/{datasetId} | Delete a dataset, optionally with all of its tables. | write | bigquery | Current | |
With deleteContents set to true, this removes every table, routine, and model inside the dataset. Acts ondataset Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TablesMethods for working with tables and their schemas.7 | ||||||
| GET | /projects/{projectId}/datasets/{datasetId}/tables | List the tables in a dataset. | read | bigquery.readonly | Current | |
Read-only. Acts ontable Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{projectId}/datasets/{datasetId}/tables/{tableId} | Retrieve a table, including its schema. | read | bigquery.readonly | Current | |
Read-only; returns metadata and schema, not the rows. Acts ontable Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /projects/{projectId}/datasets/{datasetId}/tables | Create a new table in a dataset. | write | bigquery | Current | |
Needs https://www.googleapis.com/auth/bigquery or cloud-platform. Acts ontable Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /projects/{projectId}/datasets/{datasetId}/tables/{tableId} | Update parts of a table, such as its schema or expiration, by partial replacement. | write | bigquery | Current | |
Schema changes are limited to additive and relaxing changes. Acts ontable Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /projects/{projectId}/datasets/{datasetId}/tables/{tableId} | Replace a table's metadata in full. | write | bigquery | Current | |
Overwrites the whole resource, so any field left out is cleared. Acts ontable Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /projects/{projectId}/datasets/{datasetId}/tables/{tableId} | Delete a table and its data. | write | bigquery | Current | |
Removes the table and its rows. Acts ontable Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /projects/{projectId}/datasets/{datasetId}/tables/{tableId}:setIamPolicy | Set the IAM access policy on a table. | write | bigquery | Current | |
Changes who can reach the table at the IAM level, separate from the dataset access list. Acts ontable Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Table dataMethods for streaming rows into a table and reading rows back out.2 | ||||||
| POST | /projects/{projectId}/datasets/{datasetId}/tables/{tableId}/insertAll | Stream rows into a table in near real time (the legacy streaming insert). | write | bigquery.insertdata | Current | |
https://www.googleapis.com/auth/bigquery.insertdata is the narrow scope for streaming rows; bigquery and cloud-platform also work. The Storage Write API is the newer alternative. Acts ontabledata Permission (capability) bigquery.insertdataVersionAvailable since the API’s base version Webhook eventNone Rate limit10 MB max HTTP request size SourceOfficial documentation ↗ | ||||||
| GET | /projects/{projectId}/datasets/{datasetId}/tables/{tableId}/data | Read rows from a table directly, with paging. | read | bigquery.readonly | Current | |
Read-only. Reads the stored rows without running a query. Acts ontabledata Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit3.6 GB max read per minute SourceOfficial documentation ↗ | ||||||
RoutinesMethods for working with routines, the stored functions and procedures defined in a dataset.5 | ||||||
| GET | /projects/{projectId}/datasets/{datasetId}/routines | List the routines in a dataset. | read | bigquery.readonly | Current | |
Read-only. Acts onroutine Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{projectId}/datasets/{datasetId}/routines/{routineId} | Retrieve a routine, the definition of a stored function or procedure. | read | bigquery.readonly | Current | |
Read-only. Acts onroutine Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /projects/{projectId}/datasets/{datasetId}/routines | Create a new routine in a dataset. | write | bigquery | Current | |
Defines a stored function or procedure that later queries can call. Acts onroutine Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /projects/{projectId}/datasets/{datasetId}/routines/{routineId} | Replace a routine's definition. | write | bigquery | Current | |
Overwrites the routine in full. Acts onroutine Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /projects/{projectId}/datasets/{datasetId}/routines/{routineId} | Delete a routine from a dataset. | write | bigquery | Current | |
Removes the stored function or procedure. Acts onroutine Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ModelsMethods for working with machine-learning models trained inside a dataset.4 | ||||||
| GET | /projects/{projectId}/datasets/{datasetId}/models | List the machine-learning models in a dataset. | read | bigquery.readonly | Current | |
Read-only. Acts onmodel Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{projectId}/datasets/{datasetId}/models/{modelId} | Retrieve a model and its metadata. | read | bigquery.readonly | Current | |
Read-only. Acts onmodel Permission (capability) bigquery.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /projects/{projectId}/datasets/{datasetId}/models/{modelId} | Update parts of a model, such as its description or expiration. | write | bigquery | Current | |
Edits model metadata; the model is trained through a query job, not this method. Acts onmodel Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /projects/{projectId}/datasets/{datasetId}/models/{modelId} | Delete a model from a dataset. | write | bigquery | Current | |
Removes the trained model. Acts onmodel Permission (capability) bigqueryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BigQuery does not push events to an app. An agent learns about a job by polling its status, and learns about new data by querying it.
| Event | What it signals | Triggered by |
|---|
BigQuery limits how often an app can call each method, capped per user per method, alongside separate ceilings on concurrent queries and on how much data a single read call returns.
BigQuery limits API calls per user per method, and most core methods allow up to 100 requests per user per method per second; going over returns a 403 with reason rateLimitExceeded. Separate ceilings apply to running work: an interactive query queue holds up to 1,000 queries per project per region (20,000 for batch queries), so a flood of queries waits rather than failing outright. Reads through tabledata.list are also capped by the bytes returned, not just the request count. Where a per-method limit is documented, it is shown on that method's row.
List and read methods return a page of results plus a nextPageToken (or pageToken for query results). The caller passes that token back, with maxResults to set the page size, to walk through the rest. A query that returns a large result set is read page by page through jobs.getQueryResults the same way. There is no single cursor object; the page token is the only state carried between calls.
The legacy streaming insert, tabledata.insertAll, rejects any HTTP request over 10 MB. Direct reads through tabledata.list are capped at 3.6 GB per minute per project, a limit that cannot be raised. Large query results are not returned in one response; they are paged, and very large outputs are written to a destination table and read from there.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalidQuery | The SQL has a syntax or semantic error, or the request body is otherwise invalid (also seen as invalid or badRequest). | Read the message, fix the query or request fields, and resend. The request is not retryable as-is. |
| 401 | unauthorized | No valid credentials were provided, or the access token is missing or expired. | Refresh the OAuth access token and resend with a valid Authorization header. |
| 403 | accessDenied | The identity is authenticated but lacks the IAM permission for the project, dataset, or table. | Grant the calling identity the required IAM role, or scope the request to a resource it can reach. |
| 403 | quotaExceeded | A project quota or free-tier limit was reached, named in the message property. | Reduce usage, request a quota increase, or wait for the window to reset. |
| 403 | rateLimitExceeded | Too many requests were sent too quickly for a method, user, or project. | Slow the request rate and retry with exponential backoff. |
| 404 | notFound | The referenced project, dataset, table, or job does not exist, or the request hit the wrong location. | Check the resource names and the region or location, then resend. |
| 409 | duplicate | A resource with that name already exists, for example a dataset or table being created twice. | Use a different name, or change writeDisposition to overwrite or append. |
| 500 | internalError | An error on BigQuery's side. It is rare and not caused by the request. | Retry with truncated exponential backoff, and contact support if it persists. |
| 503 | backendError | BigQuery was temporarily unable to serve the request. | Retry with truncated exponential backoff. |
BigQuery serves a single REST API version, v2, in the path, and ships dated feature changes through its release notes rather than minting a new API version for each one.
BigQuery serves one REST API version, v2, in the request path. Google does not mint a new API version per feature; dated changes ship through the release notes. Recent notable entries are listed below, newest first.
A breaking change to the Data Transfer Service: individual-user authentication for Google Ads transfers requires multi-factor authentication as of 2026-05-07.
BigQuery announced that legacy SQL usage will be limited starting 2026-06-01, based on usage patterns from November 2025 onward.
Strict act-as mode is enforced at project level for Dataform and orchestration tools, requiring custom service accounts or user credentials.
The REST surface stays at v2; track the release notes for new features and deprecations.
BigQuery release notes ↗Bollard AI sits between a team's AI agents and BigQuery. Grant each agent exactly the access it needs, read or write, dataset by dataset, and every call is checked and logged.