Objects: list

Retrieves a list of objects matching the criteria, ordered in the list lexicographically by name. Try it now.

The namespace within a bucket is flat, but the use of the delimiter parameter in conjunction with the prefix filter allows the list method to operate like a directory listing. For example, consider a bucket that contains the objects "a/b", "a/c", "d", "e", "e/f", and "e/g/h":

If delimiter is set to "/" and prefix is not set, then an object listing of the bucket returns object metadata for objects "d" and "e". It also returns "a/" and "e/" in the prefixes[] list.
If delimiter is set to "/" and prefix is set to "e/", then an object listing of the bucket returns object metadata for object "e/f". It also returns "g/" in the prefixes[] list.

The authenticated user must have sufficient permission to use this method.

Request

HTTP request

GET https://storage.googleapis.com/storage/v1/b/bucket/o

In addition to standard query parameters, the following query parameters apply to this method.

To see an example of how to include query parameters in a request, see the JSON API Overview page.

Parameters

Parameter name	Value	Description
Path parameters
`bucket`	`string`	Name of the bucket in which to look for objects.
Optional query parameters
`delimiter`	`string`	Returns results in a directory-like mode, with `/` being a common value for the delimiter. `items[]` contains object metadata for objects whose names do not contain `delimiter`, or whose names only have instances of `delimiter` in their `prefix`. `prefixes[]` contains truncated object names for objects whose names contain `delimiter` after any `prefix`. Object names are truncated beyond the first applicable instance of the delimiter. If multiple objects have the same truncated name, duplicates are omitted.
`endOffset`	`string`	Filter results to objects whose names are lexicographically before `endOffset`. If `startOffset` is also set, the objects listed have names between `startOffset` (inclusive) and `endOffset` (exclusive).
`includeTrailingDelimiter`	`boolean`	If true, objects that end in exactly one instance of `delimiter` have their metadata included in `items[]` in addition to the relevant part of the object name appearing in `prefixes[]`.
`maxResults`	`integer`	Maximum combined number of entries in `items[]` and `prefixes[]` to return in a single page of responses. Because duplicate entries in `prefixes[]` are omitted, fewer total results may be returned than requested. The service uses this parameter or 1,000 items, whichever is smaller.
`pageToken`	`string`	A previously-returned page token representing part of the larger set of results to view. The `pageToken` is an encoded field that marks the name and generation of the last object in the returned list. In a subsequent request using the `pageToken`, items that come after the `pageToken` are shown (up to `maxResults`). If you start a listing and then create an object in the bucket before using a `pageToken` to continue listing, you do not see the new object in subsequent listing results if it is in part of the object namespace already listed.
`prefix`	`string`	Filter results to include only objects whose names begin with this prefix.
`projection`	`string`	Set of properties to return. Defaults to `noAcl`. Acceptable values are: "`full`": Include all properties. "`noAcl`": Omit the `owner`, `acl` property.
`startOffset`	`string`	Filter results to objects whose names are lexicographically equal to or after `startOffset`. If `endOffset` is also set, the objects listed have names between `startOffset` (inclusive) and `endOffset` (exclusive).
`versions`	`boolean`	If `true`, lists all versions of an object as distinct results in order of increasing generation number. The default value for `versions` is `false`. For more information, see Object Versioning.

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response body with the following structure:

{
  "kind": "storage#objects",
  "nextPageToken": string,
  "prefixes": [
    string
  ],
  "items": [
    objects Resource
  ]
}

Property name	Value	Description
`kind`	`string`	The kind of item this is. For lists of objects, this is always `storage#objects`.
`nextPageToken`	`string`	The continuation token, included only if there are more items to return. Provide this value as the `pageToken` of a subsequent request in order to return the next page of results.
`prefixes[]`	`list`	Object name prefixes for objects that matched the listing request but were excluded from `items[]` because of a delimiter. Values in this list are object names up to and including the requested delimiter. Duplicate entries are omitted from this list.
`items[]`	`list`	The list of objects, ordered lexicographically by name.

Try it!

Use the APIs Explorer below to call this method on live data and see the response.