List Buckets

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

POST /v1/buckets/list

List Buckets

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "limit": 500,
  "page_size": 500,
  "offset": 5000,
  "page": 2,
  "search": "<string>",
  "filters": {},
  "sort": {},
  "sorts": [
    {}
  ],
  "case_sensitive": false
}
'

200

{
  "results": [
    {
      "bucket_name": "<string>",
      "object_count": 123,
      "total_size_bytes": 123,
      "bucket_id": "<string>",
      "description": "<string>",
      "bucket_schema": {
        "properties": {}
      },
      "unique_key": {
        "default_policy": "upsert",
        "fields": [
          "video_id"
        ]
      },
      "metadata": {},
      "storage_class": "standard",
      "destination": {
        "connection_id": "<string>",
        "prefix": ""
      },
      "ingest_filter": {
        "retriever_id": "ret_ab12cd34ef56",
        "retriever_version": 1,
        "action": "keep",
        "on_error": "keep",
        "timeout_seconds": 30
      },
      "failed_object_count": 123,
      "failed_count_measured_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "last_upload_at": "2023-11-07T05:31:56Z",
      "stats_updated_at": "2023-11-07T05:31:56Z",
      "status": "ACTIVE",
      "is_locked": false,
      "batch_stats": {
        "total": 0,
        "active": 0,
        "completed": 0,
        "completed_with_errors": 0,
        "failed": 0,
        "canceled": 0,
        "other": 0
      },
      "storage_stats": {
        "total_size_bytes": 0,
        "avg_size_bytes": 0,
        "max_size_bytes": 0,
        "min_size_bytes": 0
      },
      "source_adapter": {}
    }
  ],
  "total_count": 123,
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>",
    "next_cursor": "<string>"
  },
  "stats": {
    "total_objects": 0,
    "total_size_bytes": 0,
    "avg_objects_per_bucket": 0,
    "avg_size_per_bucket": 0
  },
  "warnings": [
    {
      "resource": "taxonomy",
      "reason": "not found in namespace",
      "next_step": "Fix the taxonomy_id on the stage, or create the taxonomy.",
      "id": "tax_abc123",
      "stage": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

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

next_cursor · string | null

after · string | null

include_total · boolean · default: false

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request model for listing buckets.

Inherits body-level limit/page_size/offset/page. 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

200

application/json

Successful Response

Response model for listing buckets.

results · BucketResponse · object[] · required

Show child attributes

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

Show child attributes

stats · BucketListStats · object | null

Aggregate statistics across all buckets in the result

Show child attributes

warnings · DegradedEntry · object[]

Why this page may not be the whole answer. An entry with resource 'namespace' and reason 'unresolved' means X-Namespace did not resolve for this API key, so the empty list is not that namespace's contents (the same condition as the X-Namespace-Unresolved response header). Empty when the namespace resolved.

Show child attributes