> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/tasks/tasks/amazon-s3/listobjects.md).

# ListObjects

Lists objects from specified AWS S3 Bucket.

Task version: 3.0.0

Required Frends version: 5.7+

Required .NET version: 8.0

Compatible Agents: Crossplatform

Source code: <https://github.com/FrendsPlatform/Frends.AmazonS3>

## Task Parameters

{% tabs %}
{% tab title="Input" %}

| Name                  | Description                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| BucketName : `String` | <p>The name of the S3 bucket to list objects from.</p><p><br>Default: <code>-</code><br>Example: <code>my-s3-bucket</code></p> |
| {% endtab %}          |                                                                                                                                |

{% tab title="Connection" %}

| Name                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 🗝AwsAccessKeyId : `String`     | <p>AWS Access Key ID used for authentication with AWS services.</p><p><br>Default: <code>-</code><br>Example: <code>AKIAQWERTY7NJ5Q7NZ6Q</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 🗝AwsSecretAccessKey : `String` | <p>AWS Secret Access Key used for authentication with AWS services.</p><p><br>Default: <code>-</code><br>Example: <code>TVh5hgd3uGY/2CqH+Kkrrg3dadbXLsYe0jC3h+WD</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Region : `Region`               | <p>AWS Region where the S3 bucket is located.</p><p>Possible values:</p><ul><li><code>AfSouth1</code>: AWS Region where the S3 bucket is located.</li><li><code>ApEast1</code>: AWS Region where the S3 bucket is located.</li><li><code>ApNortheast1</code>: AWS Region where the S3 bucket is located.</li><li><code>ApNortheast2</code>: AWS Region where the S3 bucket is located.</li><li><code>ApNortheast3</code>: AWS Region where the S3 bucket is located.</li><li><code>ApSouth1</code>: AWS Region where the S3 bucket is located.</li><li><code>ApSoutheast1</code>: AWS Region where the S3 bucket is located.</li><li><code>ApSoutheast2</code>: AWS Region where the S3 bucket is located.</li><li><code>CaCentral1</code>: AWS Region where the S3 bucket is located.</li><li><code>CnNorth1</code>: AWS Region where the S3 bucket is located.</li><li><code>CnNorthWest1</code>: AWS Region where the S3 bucket is located.</li><li><code>EuCentral1</code>: AWS Region where the S3 bucket is located.</li><li><code>EuNorth1</code>: AWS Region where the S3 bucket is located.</li><li><code>EuSouth1</code>: AWS Region where the S3 bucket is located.</li><li><code>EuWest1</code>: AWS Region where the S3 bucket is located.</li><li><code>EuWest2</code>: AWS Region where the S3 bucket is located.</li><li><code>EuWest3</code>: AWS Region where the S3 bucket is located.</li><li><code>MeSouth1</code>: AWS Region where the S3 bucket is located.</li><li><code>SaEast1</code>: AWS Region where the S3 bucket is located.</li><li><code>UsEast1</code>: AWS Region where the S3 bucket is located.</li><li><code>UsEast2</code>: AWS Region where the S3 bucket is located.</li><li><code>UsWest1</code>: AWS Region where the S3 bucket is located.</li><li><code>UsWest2</code>: AWS Region where the S3 bucket is located.</li></ul><p><br>Default: <code>-</code><br>Example: <code>EuCentral1</code></p> |
| {% endtab %}                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

{% tab title="Options" %}

| Name                             | Description                                                                                                                                                                                                                                                                               |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prefix : `String`                | <p>Limits the response to keys that begin with the specified prefix.</p><p><br>Default: <code>-</code><br>Example: <code>bucket/object1/object2</code></p>                                                                                                                                |
| Delimiter : `String`             | <p>A delimiter character used to group keys hierarchically.</p><p>See: <http://docs.aws.amazon.com/AmazonS3/latest/dev/ListingKeysHierarchy.html></p><p><br>Default: <code>-</code><br>Example: <code>/</code></p>                                                                        |
| MaxKeys : `Int32`                | <p>Sets the maximum number of keys returned in the response.</p><p>The response might contain fewer keys but will never contain more than this value.</p><p><br>Default: <code>1000</code><br>Example: <code>1000</code></p>                                                              |
| StartAfter : `String`            | <p>StartAfter specifies the key to start listing from (exclusive).</p><p>For example, in a bucket with objects { 20220401, 20220402, 20220403 },</p><p>StartAfter=20220401 returns objects 20220402 and 20220403.</p><p><br>Default: <code>-</code><br>Example: <code>20220401</code></p> |
| ThrowErrorOnFailure : `Boolean`  | <p>Determines whether to throw an exception on failure.</p><p>If set to false, returns a Result object with error information instead.</p><p><br>Default: <code>True</code><br>Example: <code>true</code></p>                                                                             |
| ErrorMessageOnFailure : `String` | <p>Custom error message to return when ThrowErrorOnFailure is false.</p><p>If not specified, the original error message will be used.</p><p><br>Default: <code>-</code><br>Example: <code>Failed to create object list</code></p>                                                         |
| {% endtab %}                     |                                                                                                                                                                                                                                                                                           |
| {% endtabs %}                    |                                                                                                                                                                                                                                                                                           |

## Task Result

| Name                            | Description                                                                                                                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Objects : `List<BucketObject>`  | <p>List of objects retrieved from the S3 bucket. Empty list if operation failed.<br>Example: <code>\[ { BucketName: "my-bucket", Key: "folder/file.txt", ... } ]</code></p>                                                          |
| Success : `Boolean`             | <p>Indicates whether the operation was successful.<br>Example: <code>true</code></p>                                                                                                                                                 |
| Error : `Error`                 | <p>Error information if the operation failed.<br>Example: <code>object { Error Message, dynamic AdditionalInfo }</code></p>                                                                                                          |
| Error.Message : `String`        | <p>The primary error message describing what went wrong.<br>Example: <code>Unable to list objects.</code></p>                                                                                                                        |
| Error.AdditionalInfo : `Object` | <p>Additional error information such as stack traces, error codes, or other diagnostic data.<br>Example: <code>object { Exception AdditionalInfo }</code></p>                                                                        |
| ErrorMessage : `String`         | <p>Error message if the operation failed. Returns empty string if operation succeeded. Provided for backward compatibility - use Error property for detailed error information.<br>Example: <code>Unable to list objects.</code></p> |

## Task Changelog

Changelog for Task Frends.AmazonS3.ListObjects.

### \[3.0.0] - 2026-07-18

#### Changed

* **\[Breaking]** The parameter order of the ListObjects task has been updated to follow the standard Frends parameter order: Input, Connection, Options. This may require reconfiguring the task in existing processes.
* Added missing documentation examples for result and error output properties.

### \[2.2.0] - 2026-06-16

#### Changed

* Updated AWSSDK.Core nuget package from 4.0.3.5 to 4.0.8
* Updated AWSSDK.S3 nuget package from 4.0.14.2 to 4.0.24.1
* Introduce more null checks to avoid unexpected exceptions

### \[2.1.0] - 2025-12-29

#### Changed

* Updated AWS SDK version.

### \[2.0.0] - 2025-07-17

### \[Breaking] Major refactoring with new class structure and error handling

#### Added

* **Connection class**: New dedicated class for AWS connection parameters
  * `AwsAccessKeyId` - AWS access key ID for authentication
  * `AwsSecretAccessKey` - AWS secret access key for authentication
  * `Region` - AWS region for the S3 service
* **Options class**: New class for task configuration options
  * `ThrowErrorOnFailure` - Boolean flag to control error throwing behavior (default: false)
  * `ErrorMessageOnFailure` - Custom error message for failures (default: empty string)
* **Error class**: New structured error handling
  * `Message` - Error message string
  * `AdditionalInfo` - Dynamic property for additional error context
* **ErrorHandler class**: New static utility class for centralized error handling
  * `Handle` method for consistent error processing across the task
* **Result.Success**: New boolean property indicating task execution success
* **Result.Error**: New error property for structured error information

#### Changed

* **\[Breaking]** Renamed `Source` class to `Input` class
* **\[Breaking]** Moved AWS credentials from Input to Connection class:
  * `Input.AwsAccessKeyId` → `Connection.AwsAccessKeyId`
  * `Input.AwsSecretAccessKey` → `Connection.AwsSecretAccessKey`
  * `Input.Region` → `Connection.Region`
* **\[Breaking]** Renamed `Result.ObjectList` to `Result.Objects`
* **\[Breaking]** Task method signature now includes Connection and Options parameters
* Improved error handling with consistent error structure and configurable error behavior

### \[1.0.0] - 2022-04-25

#### Added

* Initial implementation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.frends.com/tasks/tasks/amazon-s3/listobjects.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
