Skip to main content

List Buckets

Retrieves a list of all S3 buckets accessible with the current credentials.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Client Id - The client connection ID from the Connect node. Optional if using credentials directly.

Options​

  • End Point - S3 endpoint URL. Required only if using credentials directly instead of Client ID.
  • Access Key Id - AWS Access Key ID credential. Optional - use this instead of Client ID for direct authentication.
  • Secret Key Access - AWS Secret Access Key credential. Optional - use this instead of Client ID for direct authentication.

Output​

  • result - An array of bucket information objects. Each bucket object contains the bucket name and creation date.

How It Works​

The List Buckets node retrieves all S3 buckets that are accessible with the provided credentials. When executed, the node:

  1. Retrieves the S3 client using either the Client ID or creates a new client from credentials
  2. Sends a request to S3 to list all buckets
  3. Returns an array containing information about each bucket
  4. Each bucket object includes the bucket name and creation timestamp

Requirements​

  • Either a valid Client ID from a Connect node, or Access Key ID and Secret Access Key credentials
  • Appropriate S3 permissions to list buckets (s3:ListAllMyBuckets)

Error Handling​

The node will return specific errors in the following cases:

  • Invalid Client ID or credentials
  • Insufficient permissions to list buckets
  • Network or connection errors
  • S3 service errors

Usage Notes​

  • The node returns all buckets accessible to the credentials, regardless of region
  • Buckets from all regions are included in the response
  • The default AWS account limit is 100 buckets
  • The operation is relatively fast even with many buckets
  • The creation date is returned in ISO 8601 format
  • Buckets are not returned in any particular order

Output Structure​

The result is an array of bucket objects. Each bucket object contains:

[
  {
    "Name": "my-first-bucket",
    "CreationDate": "2024-01-15T10:30:00Z"
  },
  {
    "Name": "my-second-bucket",
    "CreationDate": "2024-02-20T14:45:00Z"
  },
  {
    "Name": "my-app-logs",
    "CreationDate": "2024-03-10T08:15:00Z"
  }
]

Best Practices​

  • Cache the bucket list if you need to reference it multiple times in a flow
  • Use List Buckets to verify a bucket exists before attempting operations
  • Filter buckets by name pattern in your flow logic if needed
  • Handle empty results gracefully (account with no buckets)
  • Consider the account bucket limit when creating new buckets programmatically
  • Use descriptive bucket names that clearly indicate their purpose

Example​

To get all buckets and process each one:

Inputs:

  • Client Id: (from Connect node)

Output:

[
  {
    "Name": "company-data-production",
    "CreationDate": "2023-06-01T00:00:00Z"
  },
  {
    "Name": "company-data-staging",
    "CreationDate": "2023-06-15T00:00:00Z"
  },
  {
    "Name": "company-backups",
    "CreationDate": "2023-07-01T00:00:00Z"
  }
]

You can then use a Loop node to iterate through each bucket and perform operations like listing objects, checking bucket size, or applying policies.

Common Use Cases​

Bucket Inventory List all buckets to create an inventory report of your S3 storage.

Bucket Validation Check if a specific bucket exists before attempting to create it:

  1. List Buckets
  2. Filter results to find matching bucket name
  3. Create bucket only if it doesn't exist

Multi-Bucket Operations Perform the same operation on all buckets:

  1. List Buckets
  2. Loop through each bucket
  3. Perform operation (e.g., list objects, check permissions, apply tags)

Bucket Cleanup Identify and clean up old or unused buckets:

  1. List Buckets
  2. Check creation date
  3. Delete buckets older than a certain threshold

Direct Credentials Example​

Options:

  • End Point: s3.amazonaws.com
  • Access Key Id: (your AWS Access Key ID credential)
  • Secret Key Access: (your AWS Secret Access Key credential)

Output: Array of all buckets accessible with the provided credentials.

Filtering Results​

While the node returns all buckets, you can filter the results in your flow:

Filter by Name Pattern: Use a Filter node or JavaScript to find buckets matching a pattern:

// Get only production buckets
const productionBuckets = buckets.filter(bucket =>
  bucket.Name.includes('production')
);

Filter by Creation Date: Find recently created buckets:

// Get buckets created in the last 30 days
const recentDate = new Date();
recentDate.setDate(recentDate.getDate() - 30);

const recentBuckets = buckets.filter(bucket =>
  new Date(bucket.CreationDate) > recentDate
);

Common Errors​

Error: "Access Denied"

  • Solution: Ensure your credentials have the s3:ListAllMyBuckets permission

Error: "Invalid Client ID"

  • Solution: Verify the Client ID from the Connect node is being passed correctly

Error: "SignatureDoesNotMatch"

  • Solution: Check that your Secret Access Key is correct and hasn't been rotated