BigQueryDataset
| Field | Type | Description | |
|---|---|---|---|
id | string | required | Dataset id. Pass this back as dataset. |
name | string | nullable | Display name |
Developers › REST API › Storage
REST API · 5 endpoints
bigquery
Complete for this group. Each operation below lists its parameters, request body, responses and errors. Every model they use is documented under Models used on this page, so you do not need another page to build a request. Base URL https://dev-api.sheetgo.com; send Authorization: Bearer sg_…. Latest version: https://dev-api.sheetgo.com/rest/reference/bigquery (Markdown).
Conventions for every endpoint. Lists take page (from 1) and per_page (1-100, default 50), and total counts pages, not items. Collection URLs end with /. POST …/run returns 200 when the run is queued; poll GET …/run. Google Sheets use provider: "drive"; column fields take letters ("E"). Error bodies and status codes: api.html#api-errors.
Python recipes. API client helper.
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.
Operations
GET/rest/beta/bigquery/projectsList 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.
Parameters
| Name | In | Type | Description | |
|---|---|---|---|---|
page | query | integer | optional | 1-based page number Default: 1 · Min: 1 |
per_page | query | integer | optional | Items per page, max 100 Default: 50 · Min: 1 · Max: 100 |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Projects visible to the account | BigQueryProjectListResponse |
| 401 | Authentication failed or token is invalid | — |
| 403 | The account lacks BigQuery permission | — |
| 412 | BigQuery is not authorized for this account | — |
| 422 | Validation Error | HTTPValidationError |
| 502 | BigQuery could not complete the request | — |
Example request
curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/bigquery/projects" \
-H "Authorization: Bearer $SHEETGO_API_KEY"Latest version: https://dev-api.sheetgo.com/rest/reference/bigquery#get-rest-beta-bigquery-projects
GET/rest/beta/bigquery/projects/{project}/datasetsList 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.
Parameters
| Name | In | Type | Description | |
|---|---|---|---|---|
project | path | string | required | Project id, as returned by GET /bigquery/projects |
page | query | integer | optional | 1-based page number Default: 1 · Min: 1 |
per_page | query | integer | optional | Items per page, max 100 Default: 50 · Min: 1 · Max: 100 |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Datasets in the project | BigQueryDatasetListResponse |
| 401 | Authentication failed or token is invalid | — |
| 403 | The account lacks BigQuery permission | — |
| 412 | BigQuery is not authorized for this account | — |
| 422 | Validation Error | HTTPValidationError |
| 502 | BigQuery could not complete the request | — |
Example request
curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/bigquery/projects/PROJECT/datasets" \
-H "Authorization: Bearer $SHEETGO_API_KEY"Latest version: https://dev-api.sheetgo.com/rest/reference/bigquery#get-rest-beta-bigquery-projects-project-datasets
GET/rest/beta/bigquery/projects/{project}/datasets/{dataset}/tablesList 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.
Parameters
| Name | In | Type | Description | |
|---|---|---|---|---|
project | path | string | required | Project id, as returned by GET /bigquery/projects |
dataset | path | string | required | Dataset id |
page | query | integer | optional | 1-based page number Default: 1 · Min: 1 |
per_page | query | integer | optional | Items per page, max 100 Default: 50 · Min: 1 · Max: 100 |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Tables in the dataset | BigQueryTableListResponse |
| 401 | Authentication failed or token is invalid | — |
| 403 | The account lacks BigQuery permission | — |
| 412 | BigQuery is not authorized for this account | — |
| 422 | Validation Error | HTTPValidationError |
| 502 | BigQuery could not complete the request | — |
Example request
curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/bigquery/projects/PROJECT/datasets/DATASET/tables" \
-H "Authorization: Bearer $SHEETGO_API_KEY"Latest version: https://dev-api.sheetgo.com/rest/reference/bigquery#get-rest-beta-bigquery-projects-project-datasets-dataset-tables
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.
Parameters
| Name | In | Type | Description | |
|---|---|---|---|---|
project | path | string | required | Project id, as returned by GET /bigquery/projects |
dataset | path | string | required | Dataset id |
table | path | string | required | Table id |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The table's typed schema and stats | BigQueryTableDetail |
| 401 | Authentication failed or token is invalid | — |
| 403 | The account lacks BigQuery permission | — |
| 404 | No such table | — |
| 412 | BigQuery is not authorized for this account | — |
| 422 | Validation Error | HTTPValidationError |
| 502 | BigQuery could not complete the request | — |
Example request
curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/bigquery/projects/PROJECT/datasets/DATASET/tables/TABLE" \
-H "Authorization: Bearer $SHEETGO_API_KEY"Latest version: https://dev-api.sheetgo.com/rest/reference/bigquery#get-rest-beta-bigquery-projects-project-datasets-dataset-tables-table
POST/rest/beta/bigquery/projects/{project}/validate-queryValidate 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.
Parameters
| Name | In | Type | Description | |
|---|---|---|---|---|
project | path | string | required | Project id, as returned by GET /bigquery/projects |
Request body (required)
application/json · ValidateQueryRequest
| Field | Type | Description | |
|---|---|---|---|
query | string | required | The SQL to check. Standard SQL; legacy SQL is not used. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The dry run's verdict | ValidateQueryResponse |
| 401 | Authentication failed or token is invalid | — |
| 403 | The account lacks BigQuery permission | — |
| 412 | BigQuery is not authorized for this account | — |
| 422 | Validation Error | HTTPValidationError |
| 502 | BigQuery could not complete the request | — |
Example request
curl -s -X POST "https://dev-api.sheetgo.com/rest/beta/bigquery/projects/PROJECT/validate-query" \
-H "Authorization: Bearer $SHEETGO_API_KEY" \
-H "Content-Type: application/json" \
-d @body.jsonLatest version: https://dev-api.sheetgo.com/rest/reference/bigquery#post-rest-beta-bigquery-projects-project-validate-query
Models used on this page
Every request and response model referenced above, including nested ones (12). The full catalogue is on api-models.html.
BigQueryDatasetListResponse
| Field | Type | Description | |
|---|---|---|---|
page | integer | nullable | Page number Default: 1 |
per_page | integer | nullable | Number of items per page Default: 50 |
results | array of BigQueryDataset | optional | List of results |
total | integer | nullable | Total number of pages Default: 0 |
truncated | boolean | optional | True when the listing hit BIGQUERY_DISCOVERY_MAX_ITEMS, so items past it are not reachable by paging.Default: false |
Used by: GET /rest/beta/bigquery/projects/{project}/datasets
BigQueryPartitioningInfo
How an existing table is partitioned.
An existing table keeps its own partitioning regardless of what a destination payload asks for, so this is what a destination will actually write into.
| Field | Type | Description | |
|---|---|---|---|
field | string | nullable | Partition column; null for ingestion-time partitioning |
granularity | string | nullable | HOUR, DAY, MONTH or YEAR |
is_ingestion_time | boolean | optional | True when partitioned by ingestion time Default: false |
type | string | nullable | The column's BigQuery type |
BigQueryProject
One GCP project visible to the authorized account.
| Field | Type | Description | |
|---|---|---|---|
id | string | required | Project id. Pass this back as project in an automation source or destination. |
name | string | nullable | Display name |
numeric_id | string | nullable | The project's numeric id. Accepted as project too, but the string id above is the readable form. |
BigQueryProjectListResponse
| Field | Type | Description | |
|---|---|---|---|
page | integer | nullable | Page number Default: 1 |
per_page | integer | nullable | Number of items per page Default: 50 |
results | array of BigQueryProject | optional | List of results |
total | integer | nullable | Total number of pages Default: 0 |
truncated | boolean | optional | True when the listing hit BIGQUERY_DISCOVERY_MAX_ITEMS, so items past it are not reachable by paging.Default: false |
Used by: GET /rest/beta/bigquery/projects
BigQueryTable
| Field | Type | Description | |
|---|---|---|---|
id | string | required | Table id. Pass this back as table. |
name | string | nullable | Display name |
BigQueryTableDetail
One table, with the typed schema a destination's partition.field needs.
| Field | Type | Description | |
|---|---|---|---|
dataset | string | required | Dataset the table belongs to. |
num_bytes | integer | nullable | Size in bytes |
num_rows | integer | nullable | Row count as BigQuery reports it |
partitioning | BigQueryPartitioningInfo | nullable | Null when the table is not partitioned |
project | string | required | Google Cloud project the table belongs to. |
schema | object (map of string → string) | optional | Column name to BigQuery type, e.g. {"Rank": "INTEGER", "created_at": "TIMESTAMP"}. A destination's partition.field must name one of these, and its type is inferred from here. |
table | string | required | The table's own id, unqualified. |
Used by: GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}
BigQueryTableListResponse
| Field | Type | Description | |
|---|---|---|---|
page | integer | nullable | Page number Default: 1 |
per_page | integer | nullable | Number of items per page Default: 50 |
results | array of BigQueryTable | optional | List of results |
total | integer | nullable | Total number of pages Default: 0 |
truncated | boolean | optional | True when the listing hit BIGQUERY_DISCOVERY_MAX_ITEMS, so items past it are not reachable by paging.Default: false |
Used by: GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables
HTTPValidationError
| Field | Type | Description | |
|---|---|---|---|
detail | array of ValidationError | optional |
Used by: GET /rest/beta/workflows/, POST /rest/beta/workflows/, POST /rest/beta/workflows/run/{id}, GET /rest/beta/workflows/{id}, PATCH /rest/beta/workflows/{id}, DELETE /rest/beta/workflows/{id}, GET /rest/beta/workflows/{id}/collaborators, POST /rest/beta/workflows/{id}/collaborators, DELETE /rest/beta/workflows/{id}/collaborators, PATCH /rest/beta/workflows/{id}/collaborators/{email}, DELETE /rest/beta/workflows/{id}/collaborators/{email}, GET /rest/beta/workflows/{id}/destinations, GET /rest/beta/workflows/{id}/files, GET /rest/beta/workflows/{id}/general-access, PUT /rest/beta/workflows/{id}/general-access, DELETE /rest/beta/workflows/{id}/general-access, POST /rest/beta/workflows/{id}/leave, POST /rest/beta/workflows/{id}/request-access, GET /rest/beta/workflows/{id}/run, POST /rest/beta/workflows/{id}/run, GET /rest/beta/workflows/{id}/sources, GET /rest/beta/automations/, POST /rest/beta/automations/run/{id}, GET /rest/beta/automations/{id}, DELETE /rest/beta/automations/{id}, GET /rest/beta/automations/{id}/destinations, GET /rest/beta/automations/{id}/files, GET /rest/beta/automations/{id}/run, POST /rest/beta/automations/{id}/run, GET /rest/beta/automations/{id}/sources, GET /rest/beta/workflows/{id}/trigger, DELETE /rest/beta/workflows/{id}/trigger, GET /rest/beta/workflows/{id}/dashboard, DELETE /rest/beta/workflows/{id}/dashboard/elements/{element_id}, GET /rest/beta/workflows/{id}/dashboard/elements/{element_id}/data, PUT /rest/beta/workflows/{id}/dashboard/publish, GET /rest/beta/workflows/{workflow_id}/forms/, POST /rest/beta/workflows/{workflow_id}/forms/, GET /rest/beta/workflows/{workflow_id}/forms/{form_id}, PATCH /rest/beta/workflows/{workflow_id}/forms/{form_id}, DELETE /rest/beta/workflows/{workflow_id}/forms/{form_id}, GET /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses, HEAD /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses, GET /rest/beta/automations/{automation_id}/webhook, GET /rest/beta/workflows/{workflow_id}/webhooks, GET /rest/beta/api-destination/{public_id}, HEAD /rest/beta/api-destination/{public_id}, GET /rest/beta/integrations/{provider}/options, GET /rest/beta/outlook/messages, POST /rest/beta/outlook/messages/batch, GET /rest/beta/outlook/messages/{message_id}, GET /rest/beta/outlook/messages/{message_id}/attachments/{attachment_id}, POST /rest/beta/outlook/send, POST /rest/beta/gmail/send, GET /rest/beta/files/{provider}, GET /rest/beta/files/{provider}/roots, GET /rest/beta/files/{provider}/search, GET /rest/beta/files/{provider}/{file_id}, GET /rest/beta/bigquery/projects, GET /rest/beta/bigquery/projects/{project}/datasets, GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables, GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}, POST /rest/beta/bigquery/projects/{project}/validate-query, POST /rest/auth/refresh, POST /rest/auth/token
ValidateQueryRequest
| Field | Type | Description | |
|---|---|---|---|
query | string | required | The SQL to check. Standard SQL; legacy SQL is not used. |
Used by: POST /rest/beta/bigquery/projects/{project}/validate-query
ValidateQueryResponse
The dry run's verdict. Nothing was scanned and nothing was mutated.
A query that will not parse is a legitimate answer here, not an error: this
endpoint returns 200 with valid: false.
| Field | Type | Description | |
|---|---|---|---|
error | string | nullable | BigQuery's explanation when valid is false |
schema | object (map of string → string) | nullable | Columns the query would return, with their types |
statement_type | string | nullable | SELECT, INSERT, DELETE, … as BigQuery classifies it. Note a valid DELETE reports valid: true — this endpoint reports what the statement is, it does not refuse writes. |
total_bytes_processed | integer | nullable | Bytes the query would scan. Use it to size the cost of an uncapped source query before creating the automation. |
valid | boolean | required | False when BigQuery rejected the SQL |
Used by: POST /rest/beta/bigquery/projects/{project}/validate-query
ValidationError
| Field | Type | Description | |
|---|---|---|---|
loc | array of string or integer | required | |
msg | string | required | |
type | string | required |