Skip to main content
POST
List Uploads

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

Example:
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'}

Example:
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

Successful Response

Response model for listing uploads.

results
UploadResponse · object[]
required

List of upload records matching the query

pagination
PaginationResponse · object
required

Pagination metadata including total count, limit, offset, has_more

stats
UploadListStats · object
required

Aggregate statistics across all uploads in the result