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 'Authorization: Bearer <token>' \
  --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"
  ],
  "return_presigned_urls": false
}
'
{
  "results": [
    {
      "bucket_id": "<string>",
      "object_id": "<string>",
      "key_prefix": "<string>",
      "blobs": [
        {
          "property": "<string>",
          "blob_id": "<string>",
          "key_prefix": "/videos/video.mp4",
          "properties": {},
          "presigned_url": "<string>",
          "details": {
            "filename": "<string>",
            "size_bytes": 123,
            "mime_type": "<string>",
            "hash": "<string>"
          }
        }
      ],
      "source_details": [
        {
          "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",
      "document_count": 123,
      "consistency": {
        "retriever_visible": "<string>",
        "recommended_header": "<string>",
        "write_token_available": false,
        "expected_visible_within_ms": 123,
        "poll": {},
        "next_actions": [
          {}
        ]
      }
    }
  ],
  "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": {}
  }
}

Authorizations

Authorization
string
header
required

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

Path Parameters

bucket_identifier
string
required

The unique identifier of the bucket.

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 objects in a bucket.

filters
LogicalOperator · object | null

Filters to apply to the object list

sort
SortOption · object | null

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"]
return_presigned_urls
boolean | null
default:false

Generate fresh presigned download URLs for all blobs with S3 storage. When true, each blob will include a 'presigned_url' in its properties. URLs expire after 1 hour.

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 | null

Aggregate statistics across all objects in the result