List multipart uploads

Lists the ongoing XML API multipart uploads for a bucket, returned in an XML document in the response body.

Uploads in the list are ordered lexicographically by the name of their associated objects, and the XML API does not return lists longer than 1000 uploads. If there are more uploads to return than can fit in the response, the response returns an IsTruncated element with a value of true. In this case, the response also contains a NextKeyMarker and a NextUploadIdMarker element which you can use in subsequent listing requests.

You can restrict and organize the list of uploads returned in the request by using the listed query string parameters.

Query string parameters

Parameter	Description	Required
`delimiter`	A character or multiple characters that can be used to simplify a list of uploads when their associated objects use a directory-like naming scheme. Can be used in conjunction with a `prefix`.	No
`encoding-type`	When set to `url`, object names are URL-encoded in the response.	No
`key-marker`	The object name after which you want to start listing. Uploads that are associated with objects whose names are lexicographically greater than the `key-marker` are returned in the list of uploads.	No
`max-uploads`	The maximum number of uploads to return in the response.	No
`prefix`	A string that limits the returned uploads to only those associated with objects whose names begin with the specified value. Can be used in conjunction with a `delimiter`.	No
`upload-id-marker`	The upload ID after which you want to start listing uploads. If you use `upload-id-marker`, you must also use `key-marker`, or else `upload-id-marker` is ignored. Uploads that are associated with the object whose names matches the `key-marker` and that are lexicographically greater than the `upload-id-marker` are returned in the list of uploads.	No
`uploads`	Indicates that the list request applies to ongoing multipart uploads in the bucket.	Yes

See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.

Request headers

See common request headers.

Request body elements

This request does not include an XML document in the request body.

Request syntax

The following syntax applies to GET Bucket requests that use the uploads query string parameter.

GET /?uploads&prefix=OBJECT_PREFIX&key-marker=OBJECT_NAME&upload-id-marker=UPLOAD_ID&max-uploads=MAX_NUM_UPLOADS&delimiter=OBJECT_DELIMITER HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE
Content-Length: 0
Authorization: AUTHENTICATION_STRING

Response headers

The request can return a variety of response headers depending on the request headers you use.

Response body elements

The following response body elements apply to GET Bucket requests that use the uploads query string parameter.

Element	Description
`ListMultipartUploadsResult`	Container for the upload information you are requesting.
`Bucket`	The name of the bucket that contains the requested multipart uploads.
`KeyMarker`	The object name at or after which the current listing begins.
`UploadIdMarker`	The upload ID after which the current listing begins.
`NextKeyMarker`	The name of the last object whose uploads were returned in this listing. This is included in the response only if the list is truncated. Use this value in the `key-marker` query string parameter of a future listing request in order to list the uploads that follow the current set of results.
`NextUploadIdMarker`	The ID of the last upload that was returned in this listing. This is included in the response only if the list is truncated. Use this value in the `upload-id-marker` query string parameter of a future listing request in order to list the uploads that follow the current set of results.
`Delimiter`	The `delimiter` that you specified in the request.
`Prefix`	The `prefix` that you specified in the request.
`MaxUploads`	The maximum number of uploads that were allowed in the response, as given by `max-uploads` in the request or 1000, whichever is smaller.
`IsTruncated`	Indicates whether or not there are uploads that do not appear in the current results due to the response containing a maximium number of uploads.
`Upload`	A container for each ongoing multipart upload in the bucket. A response can contain zero or more `Upload` elements.
`Key`	The name of the object for which the multipart upload was initiated.
`UploadId`	The upload ID that identifies the multipart upload.
`StorageClass`	The storage class for the multipart upload.
`Initiated`	The date and time when the multipart upload was initiated.
`CommonPrefixes`	Container for prefixes that satisfy your `prefix` and `delimiter` constraints. This container is used only if you specify a `delimiter` in the request, and duplicate entries are omitted. Within each `CommonPrefixes` container is a single `Prefixes` element with a prefix value.

Examples

The following sample lists the ongoing multipart uploads in a bucket named travel-maps.

Request

GET /?uploads&max-uploads=2 HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 24 Mar 2021 15:31:56 GMT
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Response

HTTP/1.1 200 OK
 Content-Length: 827
 Content-Type: application/xml
 Date: Wed, 24 Mar 2021 23:31:57 GMT
 Expires: Wed, 24 Mar 2021 23:31:57 GMT

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>travel-maps</Bucket>
  <KeyMarker></KeyMarker>
  <UploadIdMarker></UploadIdMarker>
  <NextKeyMarker>cannes.jpeg</NextKeyMarker>
  <NextUploadIdMarker>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</NextUploadIdMarker>
  <MaxUploads>2</MaxUploads>
  <IsTruncated>true</IsTruncated>
  <Upload>
    <Key>paris.jpeg</Key>
    <UploadId>VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</UploadId>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2021-11-10T20:48:33.000Z</Initiated>
  </Upload>
  <Upload>
    <Key>tokyo.jpeg</Key>
    <UploadId>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</UploadId>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2021-11-10T20:49:33.000Z</Initiated>
  </Upload>
</ListMultipartUploadsResult>

For an example of listing with the prefix and delimiter query string parameters, see the List objects reference page.