---
title: "List buckets"
method: GET
path: "/v1/buckets"
tags: ["buckets"]
---

# List buckets

`GET /v1/buckets`

List the organization's connected buckets.

Non-secret auth metadata (auth type, role ARN, external ID) is included;
access-key credentials are never returned.

Args:
    options: The pagination options.

Returns:
    BucketListResponse: The list of buckets.

## Query parameters

- `limit` integer — Maximum number of items to return per page (1-100)
- `after` string, nullable — Cursor for forward pagination - get items after this position. Use last_cursor from previous response.
- `before` string, nullable — Cursor for backward pagination - get items before this position. Use first_cursor from previous response.
- `include_total` boolean — Whether to include total count in response (expensive operation)

## Response `200`

The organization's buckets

- BucketListResponse
  - `pagination` CursorPaginationResponse, required — Response model for cursor-based pagination.
    - `has_more` boolean, required — Contextual direction-aware flag: True if more items exist in the requested pagination direction. For 'after': more items after this page. For 'before': more items before this page.
    - `first_cursor` string, nullable, required — Cursor of the first item in this page. Use for backward pagination. None if page is empty.
    - `last_cursor` string, nullable, required — Cursor of the last item in this page. Use for forward pagination. None if page is empty.
    - `total` integer, nullable — Total number of items available across all pages. Only included when include_total=true was requested. Expensive operation - use sparingly.
  - `object` 'list' — The object type of the response
  - `data` Bucket[], required — The list of buckets
    - `id` string, required — The ID of the bucket
    - `created_at` string, date-time, required — Creation time
    - `updated_at` string, date-time, required — Last update time
    - `name` string, required — Display name
    - `provider` 'aws_s3', required — Object-storage provider backing a bring-your-own bucket.
    - `bucket` string, required — The bucket name
    - `region` string, nullable, required — The bucket region
    - `endpoint_url` string, nullable, required — Custom S3-compatible endpoint
    - `prefix` string, required — Key prefix within the bucket
    - `sse_kms_key_id` string, nullable, required — KMS key id/ARN used to encrypt writes (SSE-KMS)
    - `auth_type` 'assume_role' | 'access_key', required — How omni authenticates against a customer bucket. ASSUME_ROLE is the recommended default for AWS: nothing secret is stored, every service assumes the customer's IAM role via STS on use. ACCESS_KEY remains for S3-compatible providers that have no STS.
    - `role_arn` string, nullable, required — IAM role Mixedbread assumes (auth_type=assume_role); not a secret
    - `external_id` string, nullable, required — sts:ExternalId the role's trust policy must require (auth_type=assume_role); not a secret
    - `status` 'pending' | 'active' | 'error', required — Validation lifecycle of a customer bucket.
    - `last_validated_at` string, date-time, nullable, required — When the bucket was last validated
    - `has_credentials` boolean, required — Whether secret credentials are stored (always false for assume-role buckets)
    - `credentials_version` integer, required — Increments on every credential rotation
    - `object` 'bucket' — The type of the object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mixedbread/apis/mxbai-omni.md) · [All operations](https://skmtc.net/mixedbread/apis/mxbai-omni/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixedbread/mxbai-omni/revisions/2eece97b5ae5/schema)