Objects: list

Retrieves a list of objects matching the criteria. Try it now.

In conjunction with the prefix filter, the use of the delimiter parameter allows the list method to operate like a directory listing, despite the object namespace being flat. For example, if delimiter were set to "/", then listing objects from a bucket that contains the objects "a/b", "a/c", "d", "e", "e/f" would return objects "d" and "e", and prefixes "a/" and "e/".

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:

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. `items` will contain only objects whose names, aside from the `prefix`, do not contain `delimiter`. Objects whose names, aside from the `prefix`, contain `delimiter` will have their name, truncated after the `delimiter`, returned in `prefixes`. Duplicate `prefixes` are omitted.
`endOffset`	`string`	Filter results to objects whose names are lexicographically before `endOffset`. If `startOffset` is also set, the objects listed will have names between `startOffset` (inclusive) and `endOffset` (exclusive).
`includeTrailingDelimiter`	`boolean`	If true, objects that end in exactly one instance of `delimiter` will have their metadata included in `items` in addition to `prefixes`.
`maxResults`	`integer`	Maximum number of `items` plus `prefixes` to return in a single page of responses. As duplicate `prefixes` are omitted, fewer total results may be returned than requested. The service will use 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 will 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 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 will have names between `startOffset` (inclusive) and `endOffset` (exclusive).
`versions`	`boolean`	If `true`, lists all versions of an object as distinct results. The default 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`	The list of prefixes of objects matching-but-not-listed up to and including the requested delimiter.
`items[]`	`list`	The list of objects.

Try it!

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