Skip to main content
POST
/
v1
/
buckets
/
{bucket_identifier}
/
uploads
/
list
List Uploads
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: <x-namespace>' \
  --data '{
  "description": "List all pending uploads",
  "filters": {
    "status": "PENDING"
  },
  "limit": 20,
  "offset": 0,
  "sort": {
    "direction": "desc",
    "field": "created_at"
  }
}'
{
  "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

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

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 sk_live_abc123def456"

"Bearer sk_test_xyz789"

​
X-Namespace
string
required

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
​
offset
integer | null

Body

application/json

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
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. Represents a logical operation (AND, OR, NOT) on filter conditions.

Allows nesting with a defined depth limit.

Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}).

Examples:
{ "status": "PENDING" }
{ "metadata.campaign": "summer_2024" }
{
  "AND": [
    {
      "field": "status",
      "operator": "eq",
      "value": "COMPLETED"
    },
    {
      "field": "created_at",
      "operator": "gte",
      "value": "2024-01-01T00:00:00Z"
    }
  ]
}
​
sort
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'} Specifies how to sort query results.

Attributes: field: Field to sort by direction: Sort direction (ascending or descending)

Examples:
{
  "direction": "desc",
  "field": "created_at"
}
{
  "direction": "asc",
  "field": "file_size_bytes"
}
{
  "direction": "desc",
  "field": "metadata.priority"
}
​
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'

Examples:

"video"

"summer_2024"

"profile"

​
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

Successful Response

Response model for listing uploads.

​
results
UploadResponse · object[]
required

List of upload records matching the query

​
pagination
object
required

Pagination metadata including total count, limit, offset, has_more

​
stats
object
required

Aggregate statistics across all uploads in the result