Listing the Objects of a Bucket

You can list the objects contained in your buckets or in the buckets for which you have the appropriate permissions. For more information, see Configuring an Object ACL.

This action also returns information about the date and time at which you uploaded or copied an object to your bucket.

If you organized a virtual architecture in your bucket using the keys of the objects, you can retrieve the resources that you named according to a xxx/yyy format, using the prefix and delimiter options. For more information, see About OOS > Objects.

Listing the Objects of a Bucket Using AWS CLI (s3api)

Before you begin: Install and configure AWS CLI. For more information, see Installing and Configuring AWS CLI.

This page used to feature the list-objects command, which has been deprecated in favor of the newer list-objects-v2 command. The list-objects command is still operational but has less features than the newer command.

To list the objects contained in a bucket, use the list-objects-v2 command following this syntax:

Request sample

$ aws s3api list-objects-v2 \
    --profile YOUR_PROFILE \
    --bucket BUCKET \
    --prefix "bank-data/2023/" \
    --delimiter "/" \
    --encoding-type url \
    --fetch-owner \
    --start-after NOT_SPECIFIED \
    --page-size 100 \
    --max-items 500 \
    --endpoint https://oos.eu-west-2.outscale.com

This command contains the following options that you need to specify:

(optional) profile: The named profile you want to use, created when configuring AWS CLI. For more information, see Installing and Configuring AWS CLI.
bucket: The name of the bucket whose objects you want to list.
(optional) prefix: A letter or a string of characters to filter your objects. It displays the objects that begin with the letter or the characters you specify.

If you specify a prefix, objects not starting with the specified prefix will be excluded from the output entirely.
(optional) delimiter: A character or group of characters to filter your objects by effectively excluding them from the returned list if the delimiter appears in their key name. This is useful for hierarchical naming schemes.
(optional) encoding-type: Specifies the encoding format for object key names (always url).
(optional) fetch-owner or no-fetch-owner: Whether you want to fetch the owner of the objects. When not included, the owner is not returned.
(optional) start-after: Filters the list of objects in your bucket by only showing objects coming after the key you specify, in alphabetical order.
(optional) page-size: Determines the number of requests made in a call to retrieve all objects. A smaller page size increases the number of calls but helps prevent timeouts by retrieving fewer items in each request. For example, if you have a bucket of 120 objects and you set the page size to 10, the CLI will need to perform 12 requests to retrieve all objects. If you set the page size to 60, only 2 requests will need to be performed.
The default value is 1000.

The minimum and maximum values are 1 and 1000.
(optional) max-items: The maximum number of objects to return.
endpoint: The endpoint corresponding to the Region you want to send the request to. For more information, see Installing and Configuring AWS CLI.

The list-objects-v2 command returns the following elements:

Contents: Information about the contents of your bucket. This element contains the following information:
- Key: The name of the object in the bucket.
- LastModified: The date and time when the object was uploaded or copied into the bucket.
- ETag: The ETag of the object.
- Size: The size of your object, in bytes.
- StorageClass: The storage class of your object (always STANDARD)
- Owner: Information about the owner of the object. This element contains the following information:
  - DisplayName: The OUTSCALE account ID of the owner of the object.
  - ID: The S3 user ID of the owner of the object.
CommonPrefixes: Information about the common prefixes. This element contains the following information:
- Prefix: The delimiter you specified, or the string of characters from your prefix to your delimiter. For more information about prefixes, see About OOS > Objects.
RequestCharged: Indicates whether the requester has been charged for the request. If the value is requester, it means that the cost of the operation has been billed to the account making the request. A null value suggests no charges were applied to the requester for the operation.

Result Sample

{
    "Contents": [
        {
            "Key": "bank-data/2023/annual-overview.txt",
            "LastModified": "2024-01-04T16:42:52.922000+00:00",
            "ETag": "\"93494ed0663d6a689b5e1f90d9e29d41\"",
            "Size": 2048,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "ACCOUNT_ID",
                "ID": "USER_ID"
            }
        },
        {
            "Key": "bank-data/2023/report-summary.txt",
            "LastModified": "2024-01-04T16:42:53.694000+00:00",
            "ETag": "\"b4fb2aaa356797d9a28bfc640a973720\"",
            "Size": 1024,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "ACCOUNT_ID",
                "ID": "USER_ID"
            }
        }
    ],
    "CommonPrefixes": [
        {
            "Prefix": "bank-data/2023/monthly-reports/"
        },
        {
            "Prefix": "bank-data/2023/transaction-logs/"
        }
    ],
    "RequestCharged": null
}