Method: datasets.list

Lists all datasets in the specified project to which the user has been granted the READER dataset role.

HTTP request

GET https://bigquery.googleapis.com/bigquery/v2/projects/{projectId}/datasets

The URL usesgRPC Transcoding syntax.

Path parameters

Parameters
projectId

string

Required. Project ID of the datasets to be listed

Query parameters

Parameters
maxResults

integer

The maximum number of results to return in a single response page. Leverage the page tokens to iterate through the entire collection.

pageToken

string

Page token, returned by a previous call, to request the next page of results

all

boolean

Whether to list all datasets, including hidden ones

filter

string

An expression for filtering the results of the request by label. The syntax islabels.<name>[:<value>]. Multiple filters can be AND-ed together by connecting with a space. Example:labels.department:receiving labels.active. SeeFiltering datasets using labels for details.

Request body

The request body must be empty.

Response body

Response format for a page of results when listing datasets.

If successful, the response body contains data with the following structure:

JSON representation
{"kind":string,"etag":string,"nextPageToken":string,"datasets":[{"kind":string,"id":string,"datasetReference":{object (DatasetReference)},"labels":{string:string,...},"friendlyName":string,"location":string,"externalDatasetReference":{object (ExternalDatasetReference)}}],"unreachable":[string]}
Fields
kind

string

Output only. The resource type. This property always returns the value "bigquery#datasetList"

etag

string

Output only. A hash value of the results page. You can use this property to determine if the page has changed since the last request.

nextPageToken

string

A token that can be used to request the next results page. This property is omitted on the final results page.

datasets[]

object

An array of the dataset resources in the project. Each resource contains basic information. For full information about a particular dataset resource, use the Datasets: get method. This property is omitted when there are no datasets in the project.

datasets[].kind

string

The resource type. This property always returns the value "bigquery#dataset"

datasets[].id

string

The fully-qualified, unique, opaque ID of the dataset.

datasets[].datasetReference

object (DatasetReference)

The dataset reference. Use this property to access specific parts of the dataset's ID, such as project ID or dataset ID.

datasets[].labels

map (key: string, value: string)

The labels associated with this dataset. You can use these to organize and group your datasets.

datasets[].friendlyName

string

An alternate name for the dataset. The friendly name is purely decorative in nature.

datasets[].location

string

The geographic location where the dataset resides.

datasets[].externalDatasetReference

object (ExternalDatasetReference)

Output only. Reference to a read-only external dataset defined in data catalogs outside of BigQuery. Filled out when the dataset type is EXTERNAL.

unreachable[]

string

A list of skipped locations that were unreachable. For more information about BigQuery locations, see:https://cloud.google.com/bigquery/docs/locations. Example: "europe-west5"

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/bigquery.readonly
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see theAuthentication Overview.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-02 UTC.