# bigquery

**BigQuery** can be both a source and a destination for an automation: read a table or a query's results into a spreadsheet, or load a spreadsheet's rows into a BigQuery table.

These endpoints are the discovery half — list the **projects**, **datasets** and **tables** the authorized Google account can see, read one table's **typed schema**, and **dry-run a query** to check it parses and see what it would cost before you create the automation. All of it is read-only: `validate-query` runs nothing.

Authorizing BigQuery is a Google consent screen in the Sheetgo web app and cannot be driven from an API key. Until it is granted, these endpoints answer `412`.

Base URL: `https://dev-api.sheetgo.com`. Start page: https://dev-api.sheetgo.com/rest/reference.md

This page documents every endpoint of the group. Request and response shapes link to model pages; fetch the model pages an endpoint links before building a body.

Guide: [Rate Limiting](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md)

Every endpoint is rate limited; see the guide [Rate Limiting](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md).

<a id="get-rest-beta-bigquery-projects"></a>
## GET /rest/beta/bigquery/projects

**List BigQuery projects**

Every GCP project the authorized Google account can see.

`id` is the string project id — the value an automation's `project` field
expects. `numeric_id` is the same project's numeric form, accepted too.

An empty list means the account genuinely has no BigQuery projects. A
missing authorization is a `412`, never an empty list.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `page` | query | integer | no | 1-based page number | default: `1`; min: 1 |
| `per_page` | query | integer | no | Items per page, max 100 | default: `50`; min: 1; max: 100 |

**Responses**

- `200` Projects visible to the account. Schema: [BigQueryProjectListResponse](https://dev-api.sheetgo.com/rest/reference/models/BigQueryProjectListResponse.md)
- `401` Authentication failed or token is invalid
- `412` BigQuery is not authorized for this account
- `403` The account lacks BigQuery permission
- `502` BigQuery could not complete the request
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [BigQueryProjectListResponse](https://dev-api.sheetgo.com/rest/reference/models/BigQueryProjectListResponse.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-bigquery-projects-project-datasets"></a>
## GET /rest/beta/bigquery/projects/{project}/datasets

**List a project's datasets**

Datasets in one project. `id` is what an automation's `dataset` expects.

A `bigquery` destination writes into an existing dataset — Sheetgo creates
the *table* if it is missing, but never the dataset.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `project` | path | string | yes | Project id, as returned by GET /bigquery/projects |  |
| `page` | query | integer | no | 1-based page number | default: `1`; min: 1 |
| `per_page` | query | integer | no | Items per page, max 100 | default: `50`; min: 1; max: 100 |

**Responses**

- `200` Datasets in the project. Schema: [BigQueryDatasetListResponse](https://dev-api.sheetgo.com/rest/reference/models/BigQueryDatasetListResponse.md)
- `401` Authentication failed or token is invalid
- `412` BigQuery is not authorized for this account
- `403` The account lacks BigQuery permission
- `502` BigQuery could not complete the request
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [BigQueryDatasetListResponse](https://dev-api.sheetgo.com/rest/reference/models/BigQueryDatasetListResponse.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-bigquery-projects-project-datasets-dataset-tables"></a>
## GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables

**List a dataset's tables**

Tables in one dataset. `id` is what an automation's `table` expects.

A destination may also name a table that does not exist yet — it is created
on the first run — so this listing is a convenience, not a constraint.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `project` | path | string | yes | Project id, as returned by GET /bigquery/projects |  |
| `dataset` | path | string | yes | Dataset id |  |
| `page` | query | integer | no | 1-based page number | default: `1`; min: 1 |
| `per_page` | query | integer | no | Items per page, max 100 | default: `50`; min: 1; max: 100 |

**Responses**

- `200` Tables in the dataset. Schema: [BigQueryTableListResponse](https://dev-api.sheetgo.com/rest/reference/models/BigQueryTableListResponse.md)
- `401` Authentication failed or token is invalid
- `412` BigQuery is not authorized for this account
- `403` The account lacks BigQuery permission
- `502` BigQuery could not complete the request
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [BigQueryTableListResponse](https://dev-api.sheetgo.com/rest/reference/models/BigQueryTableListResponse.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-bigquery-projects-project-datasets-dataset-tables-table"></a>
## GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}

**Read one table's schema**

One table's column types, row and byte counts, and partitioning.

The types matter for a `bigquery` destination: `partition.field` must name a
column, and BigQuery infers the partition type from that column rather than
taking it from the payload.

`partitioning` describes the table as it exists today. An existing table
keeps its own partitioning no matter what a destination payload asks for —
only `write_mode: "recreate"` replaces it.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `project` | path | string | yes | Project id, as returned by GET /bigquery/projects |  |
| `dataset` | path | string | yes | Dataset id |  |
| `table` | path | string | yes | Table id |  |

**Responses**

- `200` The table's typed schema and stats. Schema: [BigQueryTableDetail](https://dev-api.sheetgo.com/rest/reference/models/BigQueryTableDetail.md)
- `401` Authentication failed or token is invalid
- `412` BigQuery is not authorized for this account
- `403` The account lacks BigQuery permission
- `502` BigQuery could not complete the request
- `404` No such table
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [BigQueryTableDetail](https://dev-api.sheetgo.com/rest/reference/models/BigQueryTableDetail.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="post-rest-beta-bigquery-projects-project-validate-query"></a>
## POST /rest/beta/bigquery/projects/{project}/validate-query

**Validate a query without running it**

Dry-run a query: check it parses, see what it would return and cost.

Nothing is scanned and nothing can be mutated, so this is safe to call
freely — which is why it needs only the `bigquery.read` scope despite being
a POST.

**Invalid SQL answers `200` with `valid: false`**, not a 4xx: "is this
query valid?" has *no* as a legitimate answer. A `4xx`/`5xx` here means the
request could not be answered at all — missing authorization, no
permission, or BigQuery being unreachable.

Use `total_bytes_processed` to size an uncapped source query before creating
the automation. A `bigquery` source's generated SQL has no `LIMIT`, so this
is how you find out what a full scan will cost.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `project` | path | string | yes | Project id, as returned by GET /bigquery/projects |  |

**Request body**

Content type `application/json`. Required.

Body: [ValidateQueryRequest](https://dev-api.sheetgo.com/rest/reference/models/ValidateQueryRequest.md)

**Responses**

- `200` The dry run's verdict. Schema: [ValidateQueryResponse](https://dev-api.sheetgo.com/rest/reference/models/ValidateQueryResponse.md)
- `401` Authentication failed or token is invalid
- `412` BigQuery is not authorized for this account
- `403` The account lacks BigQuery permission
- `502` BigQuery could not complete the request
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [ValidateQueryRequest](https://dev-api.sheetgo.com/rest/reference/models/ValidateQueryRequest.md), [ValidateQueryResponse](https://dev-api.sheetgo.com/rest/reference/models/ValidateQueryResponse.md).

---

More: start page https://dev-api.sheetgo.com/rest/reference.md, everything in one file https://dev-api.sheetgo.com/rest/llms-full.txt, OpenAPI https://dev-api.sheetgo.com/rest/openapi.json.