list

Available in Classic and VPC

Get the list of containers (buckets) in an account or the list of objects in a container.

Note

Sub accounts cannot use the swift list command to get the list of containers in an account.

Syntax

The list syntax is as follows:

Account (queries container list)

swift list \
    [--long] \
    [--lh] \
    [--totals] \
    [--prefix <prefix>] \
    [--json] \
    [--header <header:value>]

Container (queries object list)

swift list \
    <container> \
    [--long] \
    [--lh] \
    [--totals] \
    [--prefix <prefix>] \
    [--delimiter <delimiter>] \
    [--json] \
    [--header <header:value>]

Options

This section describes the options available when running list.

Required options

The following options are required for list.

Options	Type	Required	Description
`--long`	Boolean	Conditional	Outputs detailed list in the `ls -l` format. When entering `--totals`, either `--long` or `--lh` must be entered.
`--lh`	Boolean	Conditional	Displays the size in an easy-to-read unit. When entering `--totals`, either `--long` or `--lh` must be entered.

Optional options

These are the optional options for list. Options that are not specified will use their default values.

Options	Type	Required	Description
`<container>`	String	Optional	Container name If left blank, queries the account's container list.
`--totals`	Boolean	Optional	Outputs only totals. Use along with `--long` or `--lh`.
`--prefix`	String	Optional	Retrieves only entries that begin with the specified prefix.
`--delimiter`	String	Optional	Outputs items grouped by the specified separator.
`--json`	Boolean	Optional	Outputs list information in JSON format.
`--header`	String	Optional	Custom header to use in list retrieval requests Enter in the `header:value` format.

Common options

For information about the options common to all swift subcommands, see Archive Storage options.

Examples

When you run the command, the container name or object name is displayed. Depending on the options, details such as size and last edit date are also displayed.

Command

The following is an example command for listing the containers in an account.

swift list

The following is an example command for retrieving the list of objects in a container in detailed format.

swift list test-container-01 --long --lh

The following is an example command for retrieving only the total.

swift list test-container-01 --long --lh --totals

The following describes an example command for retrieving data in JSON format.

swift list test-container-01 --json

Output

The following is an example output for retrieving the list of containers in an account.

test-container-01
test-segments-01

When you query in detailed format, the total size is displayed on the last line. The following is an example output of a query to get the object list in detailed format.

        5.0M 2026-08-19 01:53:39 application/octet-stream large.bin
          54 2026-08-19 01:53:40               text/plain renamed.txt
          54 2026-08-19 01:53:19               text/plain sample.txt
        5.0M

The following is an example output that queries only the total.

5. 0M

The following describes an example output in JSON format.

[
  {
    "bytes": 5242880,
    "content_type": "application/octet-stream",
    "hash": "8f0e1b84bfafca589762d5b0dd4f1286",
    "last_modified": "2026-08-19T01:53:39.919390",
    "name": "large.bin",
    "slo_etag": "\"207cfeb70ee1769505fcfc717e3f8be0\""
  },
  {
    "bytes": 54,
    "content_type": "text/plain",
    "hash": "448575206ef0bb80c79087a7e85c1f5c",
    "last_modified": "2026-08-19T01:53:40.342020",
    "name": "renamed.txt"
  }
]