List objects GET /v1/{account}/{container}{?limit,marker,end_marker, prefix,format,delimiter,path}

Retrieves the container details and the list of objects

Object names can be specified in the query parameter.

If omitted, up to 10,000 object names stored in the container can be retrieved.

Also, when the query parameter is used, the list of objects can be retrieved, divided by page. When the number of objects retrieved is smaller than the value specified in the limit parameter, a list right to end will be retrieved. When the number of objects retrieved equals the value specified in the limit parameter, objects that are yet to be retrieved remain in the list.

Upon successful completion, one of the following status code will be returned:
  • 200 OK: If objects exist, a list of objects is returned.
  • 204 No Content: The container does not exist or the result of filtering using the limit, marker or end_marker query parameters is empty.

If the specified container does not exist, 404 Not Found will be returned.

Note:

When a very large number of objects are created in a container, the response when obtaining the list may be delayed.To prevent lowered performance, limit the maximum number of objects registered in a single container to 1,000,000.

When retrieving a list of objects for a container in which a very large number of objects have been created, set the limit parameter (the maximum number of records to obtain) to a value of around 1,000.

Request headers

X-Auth-Token

Authentication token. If omitted, the request will fail, unless access using an ACL is permitted. Refer to ACL for details.

Data Type Cardinality
String 0..1

X-Newest

When "True" is set, object storage searches for and returns the newest replica out of all of the replicas. If this header is omitted, object storage selects one normal replica and returns it. When "True" is specified in this header, it becomes extremely costly. Only use this item when absolutely necessary.

Data Type Cardinality
Boolean 0..1

Accept

Valid values: application/json, application/xml, text/xml. This header is prioritized over the format query parameter.

Data Type Cardinality
String 0..1

Request Parameter

{account}

Name uniquely assigned by project

Data Type Cardinality
String 1..1

{container}

Container name

Data Type Cardinality
String 1..1

limit

Maximum number of lists to retrieve (1 - 10000). The default is 10000.

Data Type Cardinality
Int 0..1

marker

Returns a list of object names that follow the specified string.

Data Type Cardinality
String 0..1

end_marker

Returns a list of object names that precede the specified string.

Data Type Cardinality
String 0..1

prefix

Prefix. Returns a list of objects that start with this string.

Data Type Cardinality
String 0..1

format

Specifies the response format. Valid values: json, xml, and plain. The default is plain.

When format=xml or format=json is specified, the response will include not only the object name but also other details.

When format=plain is specified, a list of object names delimited by line feeds will be returned.

Data Type Cardinality
String 0..1

delimiter

Delimiter for nested display of object names

Data Type Cardinality
Char 0..1

path

Returns a list of object names nested using a pseudo path. This is the same as specifying "/" for "delimiter" and "{path}/" for "prefix".

Data Type Cardinality
String 0..1

Response Headers

Content-Length

Number of bytes of the response body

Data Type Cardinality
String 1..1

X-Container-Object-Count

Number of objects in the container

Data Type Cardinality
Int 1..1

Accept-Ranges

Indicates that objects included in the body can be retrieved using the Range header.

Data Type Cardinality
String 1..1

X-Container-Meta-name

Container metadata. {name} is the name of the metadata item.

Data Type Cardinality
String 1..1

X-Container-Bytes-Used

Size (in bytes) of the objects in the container

Data Type Cardinality
Int 1..1

Content-Type

MIME type of the response body

Data Type Cardinality
String 1..1

X-Trans-Id

ID assigned to this request. This is used when inquiring about issues.

Data Type Cardinality
Uuid 1..1

Date

Datetime when the transaction was executed

Data Type Cardinality
Datetime 1..1

X-Container-Read

Read permissions ACL. If omitted, this will not be returned. Refer to Read Permissions for details.

Data Type Cardinality
String 0..1

X-Container-Write

Write permissions ACL. If omitted, this will not be returned. Refer to Write Permissions for details.

Data Type Cardinality
String 0..1

Response Elements

container

Envelope of the response

Data Type Cardinality Parent Element Child Element(s)
container 1..1 None object

object

Set of object information

Data Type Cardinality Parent Element Child Element(s)
object 0..n container name

hash

bytes

content_type

last_modified

name

Object name

Data Type Cardinality Parent Element Child Element(s)
string 1..1 object None

hash

MD5 checksum of the object

Data Type Cardinality Parent Element Child Element(s)
string 1..1 object None

bytes

Size of the object

Data Type Cardinality Parent Element Child Element(s)
string 1..1 object None

content_type

MIME type of an object

Data Type Cardinality Parent Element Child Element(s)
string 1..1 object None

last_modified

Datetime when an object was created, or the datetime when the metadata was modified

Data Type Cardinality Parent Element Child Element(s)
string 1..1 object None

Example Show container details response: HTTP and JSON

Example of Request


curl -i $publicURL/marktwain?format=json -X GET -H "X-Auth-Token:$token"

Example of Response


HTTP/1.1 200 OK
Content-Length: 341
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/json; charset=utf-8
X-Trans-Id: tx26377fe5fab74869825d1-0052d6bdff
Date: Wed, 15 Jan 2014 16:57:35 GMT

[
    {
        "hash": "451e372e48e0f6b1114fa0724aa79fa1",
        "last_modified": "2014-01-15T16:41:49.390270",
        "bytes": 14,
        "name": "goodbye",
        "content_type": "application/octet-stream"
    },
    {
        "hash": "ed076287532e86365e841e92bfc50d8c",
        "last_modified": "2014-01-15T16:37:43.427570",
        "bytes": 12,
        "name": "helloworld",
        "content_type": "application/octet-stream"
    }
]

Example Show container details response: HTTP and XML

Example of Request


curl -i $publicURL/marktwain?format=xml -X GET -H "X-Auth-Token:$token"

Example of Response


HTTP/1.1 200 OK
Content-Length: 500
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/xml; charset=utf-8
X-Trans-Id: txc75ea9a6e66f47d79e0c5-0052d6be76
Date: Wed, 15 Jan 2014 16:59:35 GMT

<?xml version="1.0" encoding="UTF-8"?>
    <container name="marktwain">
    <object>
        <name>goodbye</name>
        <hash>451e372e48e0f6b1114fa0724aa79fa1</hash>
        <bytes>14</bytes>
        <content_type>application/octet-stream</content_type>
        <last_modified>2014-01-15T16:41:49.390270</last_modified>
    </object>
    <object>
        <name>helloworld</name>
        <hash>ed076287532e86365e841e92bfc50d8c</hash>
        <bytes>12</bytes>
        <content_type>application/octet-stream</content_type>
        <last_modified>2014-01-15T16:37:43.427570</last_modified>
    </object>
</container>