v10

latestOpenAPI 3.1.02026-08-085671,1112.8 MB

Buckets

List Buckets

This endpoint lists buckets with pagination, sorting, and filtering options.

post/v1/buckets/list

Query parameters

limitinteger nullable

page_sizeinteger nullable

offsetinteger nullable

pageinteger nullable

cursorstring nullable

next_cursorstring nullable

afterstring nullable

include_totalboolean

Request body

limitinteger nullable

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

page_sizeinteger nullable

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

offsetinteger nullable

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

pageinteger nullable

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

searchstring nullable

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

filtersobject nullable

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

sortobject nullable

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

sortsobject[] nullable

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_sensitiveboolean

If True, filters and search will be case-sensitive

Response

Successful Response

total_countinteger required

Total number of buckets matching the query

Example response

{
  "results": [
    {
      "unique_key": {
        "default_policy": "upsert",
        "description": "Single field, upsert by default (idempotent video ingestion)",
        "fields": [
          "video_id"
        ]
      }
    }
  ]
}