List Uploads

List uploads in a bucket with filtering, sorting, search, and pagination.

Filtering: Use LogicalOperator with shorthand syntax

• Simple: {"status": "PENDING", "metadata.campaign": "summer_2024"}
• Complex: {"AND": [{"field": "file_size_bytes", "operator": "gte", "value": 1000000}]}

Sorting: Specify field and direction

• Example: {"field": "created_at", "direction": "desc"}

Search: Full-text search across filename and metadata

• Example: "search": "video"

Pagination: Use limit and offset

• Example: "limit": 50, "offset": 100

POST /v1/buckets/{bucket_identifier}/uploads/list

List Uploads

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/uploads/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "description": "List all pending uploads",
  "filters": {
    "status": "PENDING"
  },
  "limit": 20,
  "offset": 0,
  "sort": {
    "direction": "desc",
    "field": "created_at"
  }
}
'

200

{
  "pagination": {
    "has_more": true,
    "limit": 20,
    "offset": 0,
    "total_count": 42
  },
  "results": [
    {
      "bucket_id": "bkt_prod",
      "created_at": "2024-01-15T10:30:00Z",
      "file_size_bytes": 52428800,
      "filename": "video1.mp4",
      "status": "COMPLETED",
      "upload_id": "upl_abc123"
    }
  ],
  "stats": {
    "avg_file_size_bytes": 12483047,
    "total_size_bytes": 524288000,
    "total_uploads": 42,
    "unique_buckets": 3,
    "uploads_by_status": {
      "COMPLETED": 35,
      "FAILED": 2,
      "PENDING": 5
    }
  }
}

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.

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

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 uploads with filtering, sorting, and search.

Provides flexible querying capabilities using the same filter/sort framework as documents, objects, and other list endpoints.

Supports: - Complex filters using LogicalOperator (AND, OR, NOT) - Shorthand filter syntax: {"metadata.campaign": "summer_2024"} - Full-text search across filename and metadata - Multi-field sorting - Pagination with limit/offset

Examples: - List all pending uploads in a bucket - Find uploads by metadata campaign - Search for uploads by filename pattern - Sort by file size or creation date

filters · LogicalOperator · object | null

Complex filters using logical operators (AND, OR, NOT). Supports shorthand syntax: pass field-value pairs for equality matching. Examples: - Filter by status: {'status': 'PENDING'} - Filter by metadata: {'metadata.campaign': 'summer_2024'} - Complex: {'AND': [{'field': 'status', 'operator': 'eq', 'value': 'PENDING'}, {'field': 'file_size_bytes', 'operator': 'gte', 'value': 1000000}]} See LogicalOperator documentation for full syntax.

Show child attributes

Example:

{ "status": "PENDING" }

sort · SortOption · object | null

Sort options for ordering results. Can sort by any field including metadata fields using dot notation. Default: created_at descending (newest first). Examples: - Sort by creation date: {'field': 'created_at', 'direction': 'desc'} - Sort by file size: {'field': 'file_size_bytes', 'direction': 'asc'} - Sort by metadata: {'field': 'metadata.priority', 'direction': 'desc'}

Show child attributes

Example:

{
  "direction": "desc",
  "field": "created_at"
}

search · string | null

Full-text search across filename and metadata fields. Case-insensitive partial matching. Searches in: filename, metadata values (converted to strings). Examples: - 'video' - finds 'product_video.mp4', 'tutorial_video.mov' - 'summer' - finds uploads with metadata.campaign='summer_2024'

Example:

"video"

return_presigned_urls · boolean · default: false

Whether to regenerate presigned URLs for S3 access in the response. OPTIONAL, defaults to false. If true: - Generates new GET presigned URLs for completed uploads - Useful for downloading files from S3 - Adds ~50ms per upload to response time. If false: - No presigned URLs in response - Faster response time. Note: Original PUT presigned URLs are never returned (security).

limit · integer · default: 20

Maximum number of uploads to return. OPTIONAL, defaults to 20.

Required range: 1 <= x <= 100

Examples:

20

50

100

offset · integer · default: 0

Number of uploads to skip for pagination. OPTIONAL, defaults to 0.

Required range: x >= 0

Examples:

0

20

100

Response

200

application/json

Successful Response

Response model for listing uploads.

results · UploadResponse · object[] · required

List of upload records matching the query

Show child attributes

pagination · PaginationResponse · object · required

Pagination metadata including total count, limit, offset, has_more

Show child attributes

stats · UploadListStats · object · required

Aggregate statistics across all uploads in the result

Show child attributes