Sign in Dashboard Get started
  1. Packages
  2. Packages
  3. AWS
  4. API Docs
  5. s3
  6. getBuckets
Viewing docs for AWS v7.39.0
published on Thursday, Jul 23, 2026 by Pulumi
Schema (JSON)
pulumi/pulumi-aws

aws.s3.getBuckets

aws logo
Viewing docs for AWS v7.39.0
published on Thursday, Jul 23, 2026 by Pulumi
Schema (JSON)
pulumi/pulumi-aws

    Provides details about AWS S3 (Simple Storage) buckets with optional filters.

    Example Usage

    Basic Usage

    import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = aws.s3.getBuckets({});

    import pulumi
import pulumi_aws as aws

example = aws.s3.get_buckets()

    package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/s3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := s3.GetBuckets(ctx, &s3.GetBucketsArgs{}, nil)
		if err != nil {
			return err
		}
		return nil
	})
}

    using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = Aws.S3.GetBuckets.Invoke();

});

    package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.s3.S3Functions;
import com.pulumi.aws.s3.inputs.GetBucketsArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        final var example = S3Functions.getBuckets(GetBucketsArgs.builder()
            .build());

    }
}

    variables:
  example:
    fn::invoke:
      function: aws:s3:getBuckets
      arguments: {}

    pulumi {
  required_providers {
    aws = {
      source = "pulumi/aws"
    }
  }
}

data "aws_s3_getbuckets" "example" {
}

    Full Usage

    import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = aws.s3.getBuckets({
    bucketRegion: "us-west-2",
    maxBuckets: 3,
    prefix: "tf-",
});

    import pulumi
import pulumi_aws as aws

example = aws.s3.get_buckets(bucket_region="us-west-2",
    max_buckets=3,
    prefix="tf-")

    package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/s3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := s3.GetBuckets(ctx, &s3.GetBucketsArgs{
			BucketRegion: pulumi.StringRef("us-west-2"),
			MaxBuckets:   pulumi.IntRef(3),
			Prefix:       pulumi.StringRef("tf-"),
		}, nil)
		if err != nil {
			return err
		}
		return nil
	})
}

    using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = Aws.S3.GetBuckets.Invoke(new()
    {
        BucketRegion = "us-west-2",
        MaxBuckets = 3,
        Prefix = "tf-",
    });

});

    package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.s3.S3Functions;
import com.pulumi.aws.s3.inputs.GetBucketsArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        final var example = S3Functions.getBuckets(GetBucketsArgs.builder()
            .bucketRegion("us-west-2")
            .maxBuckets(3)
            .prefix("tf-")
            .build());

    }
}

    variables:
  example:
    fn::invoke:
      function: aws:s3:getBuckets
      arguments:
        bucketRegion: us-west-2
        maxBuckets: 3
        prefix: tf-

    pulumi {
  required_providers {
    aws = {
      source = "pulumi/aws"
    }
  }
}

data "aws_s3_getbuckets" "example" {
  bucket_region = "us-west-2"
  max_buckets   = 3
  prefix        = "tf-"
}

    Using getBuckets

    Two invocation forms are available. The direct form accepts plain arguments and either blocks until the result value is available, or returns a Promise-wrapped result. The output form accepts Input-wrapped arguments and returns an Output-wrapped result.

    function getBuckets(args: GetBucketsArgs, opts?: InvokeOptions): Promise<GetBucketsResult>
function getBucketsOutput(args: GetBucketsOutputArgs, opts?: InvokeOptions): Output<GetBucketsResult>
    def get_buckets(bucket_region: Optional[str] = None,
                max_buckets: Optional[int] = None,
                prefix: Optional[str] = None,
                region: Optional[str] = None,
                opts: Optional[InvokeOptions] = None) -> GetBucketsResult
def get_buckets_output(bucket_region: pulumi.Input[Optional[str]] = None,
                max_buckets: pulumi.Input[Optional[int]] = None,
                prefix: pulumi.Input[Optional[str]] = None,
                region: pulumi.Input[Optional[str]] = None,
                opts: Optional[InvokeOptions] = None) -> Output[GetBucketsResult]
    func GetBuckets(ctx *Context, args *GetBucketsArgs, opts ...InvokeOption) (*GetBucketsResult, error)
func GetBucketsOutput(ctx *Context, args *GetBucketsOutputArgs, opts ...InvokeOption) GetBucketsResultOutput

    > Note: This function is named GetBuckets in the Go SDK.

    public static class GetBuckets 
{
    public static Task<GetBucketsResult> InvokeAsync(GetBucketsArgs args, InvokeOptions? opts = null)
    public static Output<GetBucketsResult> Invoke(GetBucketsInvokeArgs args, InvokeOptions? opts = null)
}
    public static CompletableFuture<GetBucketsResult> getBuckets(GetBucketsArgs args, InvokeOptions options)
public static Output<GetBucketsResult> getBuckets(GetBucketsArgs args, InvokeOptions options)

    fn::invoke:
  function: aws:s3/getBuckets:getBuckets
  arguments:
    # arguments dictionary
    data "aws_s3_get_buckets" "name" {
    # arguments
}

    The following arguments are supported:

    BucketRegion string
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    MaxBuckets int
    Maximum number of buckets returned. Unlike the AWS API parameter, this is a provider-level total cap.
    Prefix string
    Limits the response to bucket names that begin with the specified bucket name prefix.
    Region string
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    BucketRegion string
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    MaxBuckets int
    Maximum number of buckets returned. Unlike the AWS API parameter, this is a provider-level total cap.
    Prefix string
    Limits the response to bucket names that begin with the specified bucket name prefix.
    Region string
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    bucket_region string
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    max_buckets number
    Maximum number of buckets returned. Unlike the AWS API parameter, this is a provider-level total cap.
    prefix string
    Limits the response to bucket names that begin with the specified bucket name prefix.
    region string
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    bucketRegion String
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    maxBuckets Integer
    Maximum number of buckets returned. Unlike the AWS API parameter, this is a provider-level total cap.
    prefix String
    Limits the response to bucket names that begin with the specified bucket name prefix.
    region String
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    bucketRegion string
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    maxBuckets number
    Maximum number of buckets returned. Unlike the AWS API parameter, this is a provider-level total cap.
    prefix string
    Limits the response to bucket names that begin with the specified bucket name prefix.
    region string
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    bucket_region str
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    max_buckets int
    Maximum number of buckets returned. Unlike the AWS API parameter, this is a provider-level total cap.
    prefix str
    Limits the response to bucket names that begin with the specified bucket name prefix.
    region str
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    bucketRegion String
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    maxBuckets Number
    Maximum number of buckets returned. Unlike the AWS API parameter, this is a provider-level total cap.
    prefix String
    Limits the response to bucket names that begin with the specified bucket name prefix.
    region String
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.

    getBuckets Result

    The following output properties are available:

    Buckets List<GetBucketsBucket>
    List of bucket objects:
    Id string
    The provider-assigned unique ID for this managed resource.
    Region string
    BucketRegion string
    Bucket region.
    MaxBuckets int
    Prefix string
    Buckets []GetBucketsBucket
    List of bucket objects:
    Id string
    The provider-assigned unique ID for this managed resource.
    Region string
    BucketRegion string
    Bucket region.
    MaxBuckets int
    Prefix string
    buckets list(object)
    List of bucket objects:
    id string
    The provider-assigned unique ID for this managed resource.
    region string
    bucket_region string
    Bucket region.
    max_buckets number
    prefix string
    buckets List<GetBucketsBucket>
    List of bucket objects:
    id String
    The provider-assigned unique ID for this managed resource.
    region String
    bucketRegion String
    Bucket region.
    maxBuckets Integer
    prefix String
    buckets GetBucketsBucket[]
    List of bucket objects:
    id string
    The provider-assigned unique ID for this managed resource.
    region string
    bucketRegion string
    Bucket region.
    maxBuckets number
    prefix string
    buckets Sequence[GetBucketsBucket]
    List of bucket objects:
    id str
    The provider-assigned unique ID for this managed resource.
    region str
    bucket_region str
    Bucket region.
    max_buckets int
    prefix str
    buckets List<Property Map>
    List of bucket objects:
    id String
    The provider-assigned unique ID for this managed resource.
    region String
    bucketRegion String
    Bucket region.
    maxBuckets Number
    prefix String

    Supporting Types

    GetBucketsBucket

    BucketArn string
    Bucket ARN.
    BucketRegion string
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    CreationDate string
    Bucket creation date.
    Name string
    Bucket name.
    BucketArn string
    Bucket ARN.
    BucketRegion string
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    CreationDate string
    Bucket creation date.
    Name string
    Bucket name.
    bucket_arn string
    Bucket ARN.
    bucket_region string
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    creation_date string
    Bucket creation date.
    name string
    Bucket name.
    bucketArn String
    Bucket ARN.
    bucketRegion String
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    creationDate String
    Bucket creation date.
    name String
    Bucket name.
    bucketArn string
    Bucket ARN.
    bucketRegion string
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    creationDate string
    Bucket creation date.
    name string
    Bucket name.
    bucket_arn str
    Bucket ARN.
    bucket_region str
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    creation_date str
    Bucket creation date.
    name str
    Bucket name.
    bucketArn String
    Bucket ARN.
    bucketRegion String
    Limits the response to buckets that are located in the specified AWS Region. The AWS Region must be expressed according to the AWS Region code.
    creationDate String
    Bucket creation date.
    name String
    Bucket name.

    Package Details

    Repository
    AWS Classic pulumi/pulumi-aws
    License
    Apache-2.0
    Notes
    This Pulumi package is based on the aws Terraform Provider.
    aws logo
    Viewing docs for AWS v7.39.0
    published on Thursday, Jul 23, 2026 by Pulumi
    Schema (JSON)
    pulumi/pulumi-aws

      Try Pulumi Cloud free.
      Your team will thank you.

      Start free trial