list-objects

Available in Classic and VPC

Get the list of objects stored in a bucket.

Syntax

The list-objects syntax is as follows:

aws s3api list-objects \
    --bucket <bucket> \
    [--delimiter <delimiter>] \
    [--prefix <prefix>] \
    [--starting-token <starting-token>] \
    [--page-size <page-size>] \
    [--max-items <max-items>] \
    --endpoint-url <endpoint-url>

Options

This section describes the options available when running list-objects.

Required options

The following options are required for list-objects.

Options	Type	Required	Description
`--bucket`	String	Required	Bucket name

Optional options

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

Options	Type	Required	Description
`--delimiter`	String	Optional	Delimiter for grouping objects Groups the objects between the prefix and the delimiter into a single unit.
`--prefix`	String	Optional	Prefix to query
`--starting-token`	String	Optional	Location to start the query
`--page-size`	Integer	Optional	Number of items per page `1`-`1000`
`--max-items`	Integer	Optional	Total number of items to include in the output

Common options

For information about the options common to all aws subcommands, see Object Storage options.

Examples

If the request to retrieve the list of objects is successful, the identification information and size of each object are returned.

Command

The command example is as follows:

aws s3api list-objects --bucket my-test-bucket \
    --endpoint-url=https://kr.object.ncloudstorage.com

The following is an example command filtering objects by prefix.

aws s3api list-objects --bucket my-test-bucket \
    --prefix docs/ \
    --endpoint-url=https://kr.object.ncloudstorage.com

The following is an example command that limits the number of records retrieved at a time.

aws s3api list-objects --bucket my-test-bucket \
    --max-items 2 \
    --page-size 2 \
    --endpoint-url=https://kr.object.ncloudstorage.com

The following is an example command for retrieving the next page using the NextToken from the previous response.

aws s3api list-objects --bucket my-test-bucket \
    --max-items 2 \
    --page-size 2 \
    --starting-token eyJNYXJrZXIiOiAiaW1nL2ltYWdlLnBuZyJ9 \
    --endpoint-url=https://kr.object.ncloudstorage.com

Output

The output example is as follows:

{
    "Contents": [
        {
            "Key": "docs/report.txt",
            "LastModified": "2026-09-02T05:33:23.884Z",
            "ETag": "\"2732fae1c46437ca8a558987ed1c1229\"",
            "Size": 41,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        },
        {
            "Key": "img/image.png",
            "LastModified": "2026-09-02T06:39:50.488Z",
            "ETag": "\"2cd8bde463f5d82aae0f0cec061d6b8f\"",
            "Size": 70,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        },
        {
            "Key": "large.bin",
            "LastModified": "2026-09-02T06:41:01.883Z",
            "ETag": "\"57325bca2c5c2cb6adf5aa9a66fb4e2d\"",
            "Size": 5242880,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        },
        {
            "Key": "notes.txt",
            "LastModified": "2026-09-02T05:33:24.692Z",
            "ETag": "\"cc87f4af4dc404e7dd08a9309df6a374\"",
            "Size": 24,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        },
        {
            "Key": "sample.txt",
            "LastModified": "2026-09-02T05:33:23.549Z",
            "ETag": "\"d48c6f4176cc2713372e2a605811ec19\"",
            "Size": 46,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        }
    ],
    "RequestCharged": null
}

The following is an example output filtered by a prefix.

{
    "Contents": [
        {
            "Key": "docs/report.txt",
            "LastModified": "2026-09-02T05:33:23.884Z",
            "ETag": "\"2732fae1c46437ca8a558987ed1c1229\"",
            "Size": 41,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        }
    ],
    "RequestCharged": null
}

The following is an example output with a limit on the number of records retrieved at a time. If there is a next page, NextToken is returned along with the results.

{
    "Contents": [
        {
            "Key": "docs/report.txt",
            "LastModified": "2026-09-02T05:33:23.884Z",
            "ETag": "\"2732fae1c46437ca8a558987ed1c1229\"",
            "Size": 41,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        },
        {
            "Key": "img/image.png",
            "LastModified": "2026-09-02T06:39:50.488Z",
            "ETag": "\"2cd8bde463f5d82aae0f0cec061d6b8f\"",
            "Size": 70,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        }
    ],
    "RequestCharged": null,
    "NextToken": "eyJNYXJrZXIiOiAiaW1nL2ltYWdlLnBuZyJ9"
}

The following is an example output for querying the next page.

{
    "Contents": [
        {
            "Key": "large.bin",
            "LastModified": "2026-09-02T06:41:01.883Z",
            "ETag": "\"57325bca2c5c2cb6adf5aa9a66fb4e2d\"",
            "Size": 5242880,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        },
        {
            "Key": "notes.txt",
            "LastModified": "2026-09-02T05:33:24.692Z",
            "ETag": "\"cc87f4af4dc404e7dd08a9309df6a374\"",
            "Size": 24,
            "StorageClass": "Standard",
            "Owner": {
                "DisplayName": "ncp-123456-0",
                "ID": "ncp-123456-0"
            }
        }
    ],
    "RequestCharged": null,
    "NextToken": "eyJNYXJrZXIiOiAibm90ZXMudHh0In0="
}