Skip to main content
POST
/
v1
/
buckets
/
{bucket_identifier}
/
objects
/
list
List Objects
curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/list \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "sort": {
    "field": "created_at",
    "direction": "desc"
  },
  "search": "<string>",
  "select": [
    "metadata",
    "status",
    "created_at"
  ]
}
'
{
  "results": [
    {
      "bucket_id": "<string>",
      "object_id": "<string>",
      "key_prefix": "<string>",
      "blobs": [
        {
          "property": "<string>",
          "type": "string",
          "blob_id": "<string>",
          "key_prefix": "/videos/video.mp4",
          "properties": {},
          "details": {
            "filename": "<string>",
            "size_bytes": 123,
            "mime_type": "<string>",
            "hash": "<string>"
          }
        }
      ],
      "source_details": [
        {
          "type": "bucket",
          "source_id": "<string>"
        }
      ],
      "status": "DRAFT",
      "error": "Failed to process object: Object not found",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "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_blobs": 0,
    "avg_blobs_per_object": 0,
    "objects_by_status": {}
  }
}

Headers

​
Authorization
string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

​
X-Namespace
string

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

​
bucket_identifier
string
required

The unique identifier of the bucket.

Query Parameters

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

Body

application/json

Request model for listing objects in a bucket.

​
filters
LogicalOperator · object

Filters to apply to the object list

​
sort
SortOption · object

Sort options for the object list

​
search
string | null

Search term to filter objects by key or metadata

​
select
string[] | null

OPTIONAL. List of fields to include in the response. Supports dot notation for nested fields (e.g., 'metadata.title', 'status'). When specified, only the selected fields will be returned in the object results, reducing response size. System fields like 'object_id' and 'bucket_id' are always included. Use this to optimize response size when working with large objects.

Example:
["metadata", "status", "created_at"]

Response

Successful Response

Response model for listing objects in a bucket.

​
results
ObjectResponse · object[]
required

List of objects matching the query

​
pagination
PaginationResponse · object
required

Pagination information

​
stats
ObjectListStats · object

Aggregate statistics across all objects in the result