Objects: list

Retrieves a list of objects matching the criteria, ordered in the listlexicographically by name.

Inbuckets with a flat namespace, the use of thedelimiter parameter in conjunction with theprefix filter allows thelist 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":

  • Ifdelimiter is set to "/" andprefix 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 theprefixes[] list.
  • Ifdelimiter is set to "/" andprefix is set to "e/", then an object listing of the bucket returns object metadata for object "e/f". It also returns "g/" in theprefixes[] list.

Required permissions

The authenticated user must have thestorage.objects.list IAM permission to use this method. To return object ACLs, the authenticated user must also have thestorage.objects.getIamPolicy permission.

Request

HTTP request

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

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

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

Parameters

Parameter nameValueDescription
Path parameters
bucketstring Name of the bucket in which to look for objects.
Optional query parameters
filterstring Filter results to include only objects to which the specifiedcontext (Preview) is attached. For information about the syntax that is supported, seeFilter by object context.
delimiterstring

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 containdelimiter, or whose names only have instances ofdelimiter in theirprefix.
  • prefixes[] contains truncated object names for objects whose names containdelimiter after anyprefix, and can also contain empty folders and managed folders whenincludeFoldersAsPrefixes istrue. Object names are truncated beyond the first applicable instance of the delimiter, mimicking a directory. If multiple objects have the same truncated name, duplicates are omitted. Truncated object names inprefixes[] always end with/.

delimiter must be either excluded or set to/ in requests that use thematchGlob parameter, anddelimiter must be set to/ in requests that use theincludeFoldersAsPrefixes parameter, which returns managed folders.

endOffsetstring Filter results to objects whose names are lexicographically beforeendOffset. IfstartOffset is also set, the objects listed have names betweenstartOffset (inclusive) andendOffset (exclusive).
includeFoldersAsPrefixesboolean If true, includes empty folders andmanaged folders in results, withinprefixes[]. If this parameter is used,delimiter must be set to/.
includeTrailingDelimiterboolean If true, objects that end in exactly one instance ofdelimiter have their metadata included initems[] in addition to the relevant part of the object name appearing inprefixes[].
maxResultsinteger Maximum combined number of entries initems[] andprefixes[] to return in a single page of responses. The service may return fewer results thanmaxResults so the presence ofnextPageToken should always be checked. The recommended upper value formaxResults is 1000 objects in a single response.
matchGlobstring

Aglob pattern used to filter results (for example,foo*bar). The value must be UTF-8 encoded and has a maximum size of 1024 bytes.

Objects that match the glob are returned initems[].

Whendelimiter is used in conjunction withmatchGlob, it must be set to/. Object prefixes that contain the delimiter and match the glob are returned inprefixes[]. Ifdelimiter is not set, theprefixes[] field is empty in the response. SeeList prefixes only for information on how to list only object prefixes.

pageTokenstring A previously-returned page token representing part of the larger set of results to view.

ThepageToken is an encoded field that marks the name and generation of the last object in the returned list. In a subsequent request using thepageToken, items that come after thepageToken are shown (up tomaxResults).

If you start a listing and then create an object in the bucket before using apageToken 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.
prefixstring Filter results to include only objects whose names begin with this prefix. Whenprefix is set, the names of the objects returned in the response are relative to the root of the bucket.
projectionstring Set of properties to return. Defaults tonoAcl.

Acceptable values are:
  • full: Include all properties.
  • noAcl: Omit theowner,acl property.
startOffsetstring Filter results to objects whose names are lexicographically equal to or afterstartOffset. IfendOffset is also set, the objects listed have names betweenstartOffset (inclusive) andendOffset (exclusive).
softDeletedboolean Iftrue, only returnssoft-deleted objects as part of the objects list response. Soft-deleted objects are returned as distinct results in order of increasing generation number. ThesoftDeleted parameter can only be used successfully if the bucket has a soft delete policy. Otherwise, the request fails with a400 Bad Request error with the reasoninvalidArgument. Iftrue,versions cannot be set totrue.
versionsboolean Iftrue, lists all versions of an object as distinct results in order of increasing generation number. The default value forversions isfalse. For more information, seeObject Versioning.

Request body

Do not supply a request body with this method.

List objects and prefixes using glob

When thematchGlob query parameter is set to a glob pattern, the objects listoperation only returns objects that match the glob pattern initems[]. Whendelimiter is set to/ in conjunction withmatchGlob, theobjects list operation additionally filters results for object prefixes, where prefixes thatmatch the given glob are returned inprefixes[]. To learn how to list prefixes only,seeList prefixes only.

Cloud Storage supports the following syntax for glob patterns:

SyntaxDescriptionNotes
?Match any single character, excluding/.
*Match zero or more characters, excluding/.
**Match zero or more characters, including/.
**/Match zero or more characters that end in/. As a special case, if at a directory boundary, can match zero characters even if the trailing slash is not present. For example, the glob patternfoo/**/bar can be used to matchfoo/bar andfoo/baz/bar.A directory boundary exists at the beginning of the pattern and immediately after each slash (/).
[abc]Match exactly one of the characters between the brackets.
[a-z]Match exactly one character that is in the inclusive rangea toz.

Within a single character class, multiple ranges and characters can be used. For example,[0-9XYZa-z] is the union of[0-9],[XYZ], and[a-z].

[!abc] or[^abc]Match exactly one character that is not in the character class defined by[abc].

Within a single character class, multiple ranges and characters can be used. For example,[!0-9XYZa-z] is the intersection of[!0-9],[!XYZ], and[!a-z].

{abc,xyz}Match one ofabc orxyz.
{foo,{a,b}{x,y},bar}Match one offoo,ax,ay,bx,by, orbar.
{foo*,*bar}Match anything prefixed withfoo or suffixed withbar.Excludes/ characters.
\?Match the character after the backslash without interpreting it as a special character. Special characters are?,*,\,[,],{, and}.
Note: Brace expansions ({}) cannot contain slashes (/) or double asterisks (**).

For example, to filter for the objectfoo/bar/dog.jpeg,matchGlobshould be set tofoo/bar/*?.

List prefixes only

To usematchGlob to filter for prefixes,delimiter must be set to/. Object prefixes always end with/, so glob patterns that match atrailing/ (for example,**/) can be used to filter results to objectprefixes only. Glob patterns that match a trailing? (for example,**?)can be used to filter results to objects only.

Response

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

{"kind":"storage#objects","nextPageToken":string,"prefixes":[string],"items":[objectsResource]}
Property nameValueDescriptionNotes
kindstringThe kind of item this is. For lists of objects, this is always"storage#objects".
nextPageTokenstringThe continuation token. Provide this value as thepageToken of a subsequent request in order to return the next page of results. Note that the next page may be empty. If this is the last page of results, then no continuation token is returned. The presence of this parameter in the response should always be checked to ensure a complete listing of all the results.
prefixes[]listObject name prefixes for objects that matched the listing request but were excluded fromitems[] 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. IfmatchGlob was used in the request, only prefixes matching the glob pattern are returned.
items[]listThe list ofobjects, ordered lexicographically by name. IfmatchGlob was used in the request, only objects matching the glob pattern are returned.

For information about status and error codes returned by this API, see thereference page.

Try it!

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

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 2026-02-19 UTC.