Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Bucket Uploads

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

Path parameters

bucket_identifierstring required

The unique identifier of the bucket

The unique identifier of the bucket

Query parameters

limitinteger nullable
page_sizeinteger nullable
offsetinteger nullable
pageinteger nullable
cursorstring nullable
next_cursorstring nullable
afterstring nullable
include_totalboolean

Request body

searchstring nullable

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'

return_presigned_urlsboolean

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

limitinteger

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

offsetinteger

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

Example request

{
  "description": "List all pending uploads",
  "filters": {
    "status": "PENDING"
  },
  "limit": 20,
  "offset": 0,
  "sort": {
    "direction": "desc",
    "field": "created_at"
  }
}

Response

Successful Response

Example response

{
  "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
    }
  }
}