# ListBuckets

ListBuckets returns the buckets in your account, in alphabetical order by name. Each STRG
endpoint serves exactly one region, so the answer holds the buckets in the endpoint's region -
and asking each regional endpoint in turn gives you every bucket you own.

**Info: Good to know on STRG**

- The list covers the endpoint's region, so one request per region adds up to your whole
  account - the [examples](https://docs.strg.com/s3-api/ListBuckets#examples) include a loop that does it.
- Every matching bucket comes back in one answer, so there is no next page to fetch.
  `max-buckets` and `continuation-token` are welcome and change nothing, and no
  `ContinuationToken` comes back.
- `BucketRegion` and the echoed `Prefix` are left out of the response: every listed bucket is in
  the endpoint's region, and `prefix` still filters the list.
- An access key limited to some buckets lists them when it holds **List all bucket names**;
  without it, ListBuckets answers `403 AccessDenied`.

## When you'd use it

- **S3 tools getting started.** File browsers, backup tools and commands such as `aws s3 ls` list
  the buckets first, to show what is there or to check that the credentials work.
- **Keeping an inventory.** A nightly script asks each regional endpoint for its buckets and
  reports what exists where, or notices that a bucket it expects is missing.
- **Checking before creating.** A deploy script can look for its own buckets by name with
  `prefix` - `my-app-`, say - and create only the ones that are not there yet.
- **An agent finding its way around.** An AI agent handed an access key can list the buckets
  first, to learn where its work belongs before it reads or writes anything.

## Request

```http
GET / HTTP/1.1
Host: s3.eu-central-1.strg.com
Authorization: AWS4-HMAC-SHA256 Credential=...
x-amz-date: 20260926T120000Z
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

ListBuckets names no bucket, so it always goes to the regional endpoint itself,
`s3.<region>.strg.com`. A `GET /` on a virtual-hosted bucket hostname
(`my-bucket.s3.eu-central-1.strg.com`) is [ListObjects](https://docs.strg.com/s3-api/ListObjects) instead -
[Addressing](https://docs.strg.com/s3-api/overview#addressing) explains both forms.

### Permissions

What a key sees depends on its scope:

| Access key | Result |
| --- | --- |
| All buckets | Every bucket in the endpoint's region. |
| Some buckets, with **List all bucket names** (`buckets:list-all`) | Every bucket in the endpoint's region, including those the key cannot otherwise reach. |
| Some buckets, without **List all bucket names** | `403 AccessDenied`. |

Every access key holds **List buckets** (`buckets:list`). Many S3 tools and SDKs call ListBuckets
before anything else, so a key limited to some buckets usually works best with **List all bucket
names** as well. [Access keys](https://docs.strg.com/access-keys) has the details.

### URI parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `prefix` | String | No | Lists only buckets whose names begin with this string. |
| `bucket-region` | String | No | Lists only buckets in this region. An endpoint lists its own region, so a value naming the endpoint's region changes nothing, and any other value returns an empty list. |
| `max-buckets` | Integer | No | Welcome, and changes nothing: every matching bucket comes back in one answer. |
| `continuation-token` | String | No | Welcome, and changes nothing: STRG never returns a `ContinuationToken`, so there is never a next page to ask for. |

Any other query parameter answers `501 NotImplemented`, so a client knows straight away.

### Request headers

No operation-specific headers.

### Request body

None.

## Response

A successful request answers `200 OK` with an XML body.

### Response headers

| Name | Description |
| --- | --- |
| `Content-Type` | `application/xml`. |
| `x-amz-request-id` | The request ID, handy for a support request. |

### Response body

| Element | Type | Description |
| --- | --- | --- |
| `ListAllMyBucketsResult` | Container | The root element. |
| `Owner` | Container | The account that owns the buckets. |
| `Owner/ID` | String | Your STRG account ID. |
| `Owner/DisplayName` | String | Your STRG account ID, the same value as `ID`. |
| `Buckets` | Container | The buckets. Empty when none match. |
| `Buckets/Bucket` | Container | One bucket. |
| `Buckets/Bucket/Name` | String | The bucket's name. |
| `Buckets/Bucket/CreationDate` | Timestamp | When the bucket was created. |
| `Buckets/Bucket/BucketRegion` | String | Not returned: every listed bucket is in the endpoint's region. |
| `ContinuationToken` | String | Not returned: the whole list is always in one answer. |
| `Prefix` | String | Not returned, even when the request carried `prefix`. |

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>usr_01K5ZQ8M3T4VW6XY7Z8A9BCDEF</ID>
    <DisplayName>usr_01K5ZQ8M3T4VW6XY7Z8A9BCDEF</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <Name>my-bucket</Name>
      <CreationDate>2026-01-15T09:30:00.000Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>my-other-bucket</Name>
      <CreationDate>2026-03-02T17:04:12.000Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>
```

## Errors

These are the errors this request can return, and the situation behind each one.

| Code | HTTP status | When |
| --- | --- | --- |
| `AccessDenied` | 403 | The access key is limited to some buckets and does not hold **List all bucket names**, the account is not active, or the request is unsigned. |
| `InvalidAccessKeyId` | 403 | The access key does not exist, has expired or been revoked - or it was created moments ago and is not usable yet in this endpoint's region, in which case the same request works shortly afterwards. |
| `SignatureDoesNotMatch` | 403 | The request signature does not match. |
| `RequestTimeTooSkewed` | 403 | The request time is more than 15 minutes from the server's. |
| `AuthorizationHeaderMalformed` | 400 | The signature's credential scope names a region other than the endpoint's. |
| `NotImplemented` | 501 | The request carries a query parameter this operation does not take. |
| `SlowDown` | 503 | Too many requests. The `Retry-After` header says when a retry is welcome; the AWS SDKs retry on their own. |
| `ServiceUnavailable` | 503 | A temporary failure; the same request can be retried. |

A region where your account has never stored anything answers `200 OK` with an empty `Buckets`
element, which is the truth: there are no buckets there. Listing across regions needs no special
handling for it.

## Differences from Amazon S3

Each row is something STRG does its own way, and what that means for your code.

| Aspect | Amazon S3 | STRG |
| --- | --- | --- |
| Which buckets | Every bucket in the account, from any regional endpoint | The buckets in the endpoint's region. Asking each regional endpoint gives the whole account |
| Pagination | `max-buckets` and `continuation-token` page through the list | Every matching bucket is in one answer and no `ContinuationToken` comes back, so a paginating client simply finishes after its first page with the whole list |
| `BucketRegion` | Returned for each bucket | Not returned - every bucket listed is in the endpoint's region |
| `Prefix` in the response | Echoed when the request carried `prefix` | Not returned. `prefix` still filters the list |
| Key limited to some buckets | Governed by IAM policy | Lists every bucket in the region when the key holds **List all bucket names**; without it, `403 AccessDenied` |
| Account with no storage in the region | - | An empty list, `200 OK` |
| `Owner` | Your AWS canonical user ID | Your STRG account ID, in both `ID` and `DisplayName` |

## Examples

**AWS CLI**

```bash
aws s3api list-buckets \
  --endpoint-url https://s3.eu-central-1.strg.com \
  --region eu-central-1
```

Only the buckets whose names begin with `logs-`:

```bash
aws s3api list-buckets \
  --prefix logs- \
  --endpoint-url https://s3.eu-central-1.strg.com \
  --region eu-central-1
```

**Python (boto3)**

```python
import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.eu-central-1.strg.com",
    region_name="eu-central-1",
)

response = s3.list_buckets()
for bucket in response["Buckets"]:
    print(bucket["Name"], bucket["CreationDate"])

# Only the buckets whose names begin with "logs-"
response = s3.list_buckets(Prefix="logs-")
print([bucket["Name"] for bucket in response["Buckets"]])
```

**JavaScript (AWS SDK v3)**

```javascript
import { ListBucketsCommand, S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({
  endpoint: "https://s3.eu-central-1.strg.com",
  region: "eu-central-1",
});

const response = await client.send(new ListBucketsCommand({}));
for (const bucket of response.Buckets ?? []) {
  console.log(bucket.Name, bucket.CreationDate);
}

// Only the buckets whose names begin with "logs-"
const filtered = await client.send(new ListBucketsCommand({ Prefix: "logs-" }));
console.log((filtered.Buckets ?? []).map((bucket) => bucket.Name));
```

Listing every bucket in your account, by asking each regional endpoint:

**AWS CLI**

```bash
for region in us-east-1 eu-central-1; do
  aws s3api list-buckets \
    --endpoint-url "https://s3.${region}.strg.com" \
    --region "${region}" \
    --query 'Buckets[].Name' \
    --output text | tr '\t' '\n' | sed "s/^/${region} /"
done
```

**Python (boto3)**

```python
import boto3

for region in ["us-east-1", "eu-central-1"]:
    s3 = boto3.client(
        "s3",
        endpoint_url=f"https://s3.{region}.strg.com",
        region_name=region,
    )
    response = s3.list_buckets()
    for bucket in response["Buckets"]:
        print(region, bucket["Name"])
```

**JavaScript (AWS SDK v3)**

```javascript
import { ListBucketsCommand, S3Client } from "@aws-sdk/client-s3";

for (const region of ["us-east-1", "eu-central-1"]) {
  const client = new S3Client({ endpoint: `https://s3.${region}.strg.com`, region });
  const response = await client.send(new ListBucketsCommand({}));
  for (const bucket of response.Buckets ?? []) {
    console.log(region, bucket.Name);
  }
}
```

## Related

- [HeadBucket](https://docs.strg.com/s3-api/HeadBucket) - checking that one bucket exists in the endpoint's region
- [GetBucketLocation](https://docs.strg.com/s3-api/GetBucketLocation)
- [ListObjectsV2](https://docs.strg.com/s3-api/ListObjectsV2) - listing the objects in a bucket
- [S3 API overview](https://docs.strg.com/s3-api/overview#regions-and-endpoints) - regions and their endpoints
- [Access keys](https://docs.strg.com/access-keys)