Skip to main content
POST
List Buckets

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

limit
integer | null
Required range: 1 <= x <= 1000
page_size
integer | null
Required range: 1 <= x <= 1000
offset
integer | null
Required range: 0 <= x <= 10000
page
integer | null
Required range: x >= 1
cursor
string | null
include_total
boolean
default:false

Body

application/json

Request model for listing buckets.

Inherits body-level limit/page_size/offset/page (BACKE-2846). The old hardcoded limit=10/offset=0 defaults moved to the controller so an unset body field can fall back to query-string pagination (body wins when set).

limit
integer | null

Page size. A body value wins over the limit query param.

Required range: 1 <= x <= 1000
page_size
integer | null

Alias for limit (page size). If both are given, limit wins.

Required range: 1 <= x <= 1000
offset
integer | null

Number of results to skip (legacy, use cursor instead). A body value wins over the offset query param.

Required range: 0 <= x <= 10000
page
integer | null

1-indexed page number. Folds to offset = (page-1) * limit. If both page and offset are given, offset wins.

Required range: x >= 1
search
string | null

Search term for wildcard search across bucket_id, bucket_name, description, and other text fields

filters
Filters · object | null

Filters to apply to the bucket list. Supports filtering by bucket_id or bucket_name.

sort
Sort · object | null

Sort options for the bucket list (single-column, legacy)

sorts
Sorts · object[] | null

Sort options for the bucket list as a list of {field, direction} — the shape Studio datatables and the retriever list send. The first entry is the primary sort. Takes precedence over the singular sort.

case_sensitive
boolean
default:false

If True, filters and search will be case-sensitive

Response

Successful Response

Response model for listing buckets.

results
BucketResponse · object[]
required
total_count
integer
required

Total number of buckets matching the query

pagination
PaginationResponse · object
required

PaginationResponse.

Cursor-based pagination response:

  • Use next_cursor for navigation
  • Total count fields only populated when include_total=true
stats
BucketListStats · object | null

Aggregate statistics across all buckets in the result