> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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` ## OpenAPI ````yaml post /v1/buckets/{bucket_identifier}/uploads/list openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/buckets/{bucket_identifier}/uploads/list: post: tags: - Bucket Uploads summary: List Uploads description: >- 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` operationId: list_uploads_v1_buckets__bucket_identifier__uploads_list_post parameters: - name: bucket_identifier in: path required: true schema: type: string description: The unique identifier of the bucket title: Bucket Identifier description: The unique identifier of the bucket - name: limit in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Limit - name: page_size in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Page Size - name: offset in: query required: false schema: anyOf: - type: integer maximum: 10000 minimum: 0 - type: 'null' title: Offset - name: page in: query required: false schema: anyOf: - type: integer minimum: 1 - type: 'null' title: Page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor - name: include_total in: query required: false schema: type: boolean default: false title: Include Total requestBody: content: application/json: schema: $ref: '#/components/schemas/ListUploadsRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListUploadsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ListUploadsRequest: properties: filters: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - type: 'null' description: >- 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. 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: anyOf: - $ref: '#/components/schemas/SortOption' - type: 'null' description: >- 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'} examples: - direction: desc field: created_at - direction: asc field: file_size_bytes - direction: desc field: metadata.priority search: anyOf: - type: string - type: 'null' title: Search description: >- 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: type: boolean title: Return Presigned Urls description: >- 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). default: false limit: type: integer maximum: 100 minimum: 1 title: Limit description: Maximum number of uploads to return. OPTIONAL, defaults to 20. default: 20 examples: - 20 - 50 - 100 offset: type: integer minimum: 0 title: Offset description: Number of uploads to skip for pagination. OPTIONAL, defaults to 0. default: 0 examples: - 0 - 20 - 100 type: object title: ListUploadsRequest description: >- 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 examples: - description: List all pending uploads filters: status: PENDING limit: 20 offset: 0 sort: direction: desc field: created_at - description: Find large completed uploads filters: AND: - field: status operator: eq value: COMPLETED - field: file_size_bytes operator: gte value: 10485760 limit: 50 sort: direction: desc field: file_size_bytes - description: Search for video uploads in summer campaign filters: metadata.campaign: summer_2024 limit: 100 search: video - description: List failed uploads for debugging filters: status: FAILED limit: 50 return_presigned_urls: true sort: direction: desc field: created_at ListUploadsResponse: properties: results: items: $ref: '#/components/schemas/UploadResponse' type: array title: Results description: List of upload records matching the query pagination: $ref: '#/components/schemas/PaginationResponse' description: Pagination metadata including total count, limit, offset, has_more stats: $ref: '#/components/schemas/UploadListStats' description: Aggregate statistics across all uploads in the result type: object required: - results - pagination - stats title: ListUploadsResponse description: Response model for listing uploads. examples: - 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 ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError LogicalOperator-Input: properties: AND: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: And description: Logical AND operation - all conditions must be true example: - field: name operator: eq value: John - field: age operator: gte value: 30 OR: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: Or description: Logical OR operation - at least one condition must be true example: - field: status operator: eq value: active - field: role operator: eq value: admin NOT: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: Not description: Logical NOT operation - all conditions must be false example: - field: department operator: eq value: HR - field: location operator: eq value: remote case_sensitive: anyOf: - type: boolean - type: 'null' title: Case Sensitive description: Whether to perform case-sensitive matching default: false example: true additionalProperties: true type: object title: LogicalOperator description: >- 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"}). SortOption: properties: field: type: string title: Field description: Field to sort by, supports dot notation for nested fields example: created_at direction: $ref: '#/components/schemas/SortDirection' description: Sort direction default: asc example: desc type: object required: - field title: SortOption description: |- Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending) UploadResponse: properties: upload_id: type: string title: Upload Id description: >- Unique identifier for this upload. Auto-generated. ⚠️ NEXT STEP: After uploading to S3, you MUST confirm: POST /v1/uploads/{upload_id}/confirm Other operations: - Check status: GET /v1/uploads/{upload_id} - Cancel upload: DELETE /v1/uploads/{upload_id} Format: 'upl_' followed by 16 random characters. examples: - upl_a1b2c3d4e5f6 - upl_x9y8z7w6v5u4 bucket_id: type: string title: Bucket Id description: Target bucket ID where object will be created examples: - bkt_abc123 filename: type: string title: Filename description: Name of the file to upload examples: - product_video.mp4 content_type: type: string title: Content Type description: MIME type enforced by the presigned URL examples: - video/mp4 file_size_bytes: anyOf: - type: integer - type: 'null' title: File Size Bytes description: >- Expected file size in bytes if provided in request. Will be validated during confirmation. examples: - 10485760 presigned_url: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Presigned Url description: >- Time-limited HTTPS URL for uploading directly to S3. **Step 1 - Upload to S3:** curl -X PUT '{presigned_url}' -H 'Content-Type: {content_type}' --upload-file {filename} **Step 2 - REQUIRED: Confirm the upload:** POST /v1/uploads/{upload_id}/confirm (S3 has no callback - you MUST call confirm to finalize) The URL includes authentication and expires after presigned_url_expiration seconds. S3 returns an ETag header on success - pass it to confirm for integrity validation. NOTE: This will be null if is_duplicate=true (duplicate found, no upload needed). presigned_url_expiration: type: integer title: Presigned Url Expiration description: How long the presigned URL is valid, in seconds examples: - 3600 s3_key: type: string title: S3 Key description: >- Full S3 object key where the file will be stored. Format: {internal_id}/{namespace_id}/api_buckets_uploads_create/{upload_id}/{filename}. Used internally for verification and object creation. examples: - int_xyz/ns_abc/api_buckets_uploads_create/upl_123/video.mp4 status: $ref: '#/components/schemas/TaskStatusEnum' description: >- Current upload status. After creation, always PENDING. Possible statuses: PENDING → IN_PROGRESS → PROCESSING → COMPLETED/FAILED/CANCELED examples: - PENDING metadata: additionalProperties: true type: object title: Metadata description: Custom metadata for tracking create_object_on_confirm: type: boolean title: Create Object On Confirm description: Whether bucket object will be auto-created on confirmation object_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Object Metadata description: Metadata for the bucket object (if create_object_on_confirm=true) blob_property: anyOf: - type: string - type: 'null' title: Blob Property description: Property name for the blob in bucket object blob_type: anyOf: - type: string - type: 'null' title: Blob Type description: Type of blob (IMAGE, VIDEO, etc.) file_hash: anyOf: - type: string - type: 'null' title: File Hash description: >- SHA256 hash of the file content. Set during confirmation from S3 metadata or provided in request. Used for duplicate detection. examples: - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 skip_duplicates: type: boolean title: Skip Duplicates description: Whether duplicate detection was enabled for this upload default: true is_duplicate: type: boolean title: Is Duplicate description: >- Whether this upload was identified as a duplicate of an existing file. If true: - duplicate_of_upload_id contains the original upload - presigned_url will be null (no upload needed) - You can use the original upload's S3 object. This saves bandwidth and storage costs. default: false duplicate_of_upload_id: anyOf: - type: string - type: 'null' title: Duplicate Of Upload Id description: >- If skip_duplicates=true and duplicate found, this is the original upload_id. The response will reference the existing upload instead of creating a new one. examples: - upl_original123 skipped_unique_key: type: boolean title: Skipped Unique Key description: >- Whether this upload was skipped because the unique key already exists in the bucket. If true: - existing_object_id contains the ID of the existing object - presigned_url will be null (no upload needed) - No S3 upload is required This saves bandwidth and prevents duplicate objects. default: false existing_object_id: anyOf: - type: string - type: 'null' title: Existing Object Id description: >- If skipped_unique_key=true, this is the object_id of the existing object that has the same unique key values. The upload was skipped to prevent duplicates. examples: - obj_abc123xyz789 message: anyOf: - type: string - type: 'null' title: Message description: >- Human-readable message about the upload. Provided when is_duplicate=true or other special conditions. Example: 'File already exists with the same content hash. No upload needed - returning existing upload.' created_at: type: string format: date-time title: Created At description: When this upload record was created (ISO 8601 format) examples: - '2024-01-15T10:30:00Z' expires_at: type: string format: date-time title: Expires At description: >- When the presigned URL expires (ISO 8601 format). After this time: - The presigned URL cannot be used - Upload status will be marked as FAILED if not completed - The upload record will be auto-deleted 30 days later (MongoDB TTL) examples: - '2024-01-15T11:30:00Z' completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: When the upload was completed and verified (ISO 8601 format) examples: - '2024-01-15T10:35:00Z' verified_at: anyOf: - type: string format: date-time - type: 'null' title: Verified At description: When S3 object existence was verified (ISO 8601 format) examples: - '2024-01-15T10:35:00Z' etag: anyOf: - type: string - type: 'null' title: Etag description: S3 ETag from the uploaded object (set during confirmation) examples: - d41d8cd98f00b204e9800998ecf8427e object_id: anyOf: - type: string - type: 'null' title: Object Id description: Created bucket object ID (if create_object_on_confirm was true) examples: - obj_a1b2c3d4e5f6 task_id: anyOf: - type: string - type: 'null' title: Task Id description: Task ID for async confirmation (if processed asynchronously) examples: - task_abc123 type: object required: - upload_id - bucket_id - filename - content_type - presigned_url_expiration - s3_key - status - create_object_on_confirm - created_at - expires_at title: UploadResponse description: >- Response containing presigned URL and upload tracking information. This response includes everything needed to: 1. Upload your file to S3 using the presigned_url 2. Track the upload status using upload_id 3. Confirm the upload using the confirmation endpoint The presigned_url is time-limited and specific to this upload. After uploading to S3, call POST /v1/buckets/{bucket_id}/uploads/{upload_id}/confirm. examples: - blob_property: video blob_type: VIDEO bucket_id: bkt_prod_videos content_type: video/mp4 create_object_on_confirm: true created_at: '2024-01-15T10:30:00Z' description: >- New upload ready for S3 - object will be created on confirm (DEFAULT) expires_at: '2024-01-15T11:30:00Z' file_size_bytes: 52428800 filename: product_demo.mp4 is_duplicate: false object_metadata: category: tutorials presigned_url: https://s3.amazonaws.com/bucket/key?X-Amz-Signature=... presigned_url_expiration: 3600 s3_key: >- int_xyz/ns_abc/api_buckets_uploads_create/upl_abc123xyz789/product_demo.mp4 skip_duplicates: true status: PENDING upload_id: upl_abc123xyz789 - bucket_id: bkt_prod_videos completed_at: '2024-01-10T08:25:00Z' content_type: video/mp4 created_at: '2024-01-10T08:20:00Z' description: Duplicate detected - no upload needed, existing object returned duplicate_of_upload_id: upl_original456 file_hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 file_size_bytes: 52428800 filename: product_demo.mp4 is_duplicate: true message: >- File already exists with the same content hash. No upload needed - returning existing upload. object_id: obj_existing789 s3_key: >- int_xyz/ns_abc/api_buckets_uploads_create/upl_original456/product_demo.mp4 status: COMPLETED upload_id: upl_original456 - bucket_id: bkt_media content_type: video/mp4 create_object_on_confirm: false created_at: '2024-01-15T10:30:00Z' description: 'ADVANCED: Manual object creation (create_object_on_confirm=false)' expires_at: '2024-01-15T11:30:00Z' filename: video.mp4 note: Only use when combining multiple uploads into one object presigned_url: https://s3.amazonaws.com/bucket/key?X-Amz-Signature=... presigned_url_expiration: 3600 s3_key: int_xyz/ns_abc/api_buckets_uploads_create/upl_manual789/video.mp4 status: PENDING upload_id: upl_manual789 workflow: - 1. User uploads file to presigned_url - >- 2. POST /uploads/upl_manual789/confirm (verifies upload, no object created) - '3. POST /buckets/{id}/objects with upload_id reference:' - ' {blobs: [{property: ''video'', upload_id: ''upl_manual789''}]}' PaginationResponse: properties: total: anyOf: - type: integer - type: 'null' title: Total page: anyOf: - type: integer - type: 'null' title: Page page_size: anyOf: - type: integer - type: 'null' title: Page Size total_pages: anyOf: - type: integer - type: 'null' title: Total Pages next_page: anyOf: - type: string - type: 'null' title: Next Page previous_page: anyOf: - type: string - type: 'null' title: Previous Page next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor type: object title: PaginationResponse description: |- PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true UploadListStats: properties: total_uploads: type: integer title: Total Uploads description: Total number of uploads in the result set total_size_bytes: type: integer title: Total Size Bytes description: Total size of all files in bytes uploads_by_status: additionalProperties: type: integer type: object title: Uploads By Status description: Count of uploads grouped by status examples: - COMPLETED: 35 FAILED: 2 PENDING: 5 avg_file_size_bytes: type: number title: Avg File Size Bytes description: Average file size across all uploads unique_buckets: type: integer title: Unique Buckets description: Number of unique buckets in the result set type: object required: - total_uploads - total_size_bytes - uploads_by_status - avg_file_size_bytes - unique_buckets title: UploadListStats description: Aggregate statistics for a list of uploads. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError FilterCondition: properties: field: type: string title: Field description: Field name to filter on operator: $ref: '#/components/schemas/FilterOperator' description: Comparison operator default: eq value: anyOf: - $ref: '#/components/schemas/DynamicValue' - {} title: Value description: Value to compare against type: object required: - field - value title: FilterCondition description: |- Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against SortDirection: type: string enum: - asc - desc title: SortDirection description: Sort direction options. TaskStatusEnum: type: string enum: - PENDING - QUEUED - IN_PROGRESS - PROCESSING - COMPLETED - COMPLETED_WITH_ERRORS - FAILED - CANCELED - INTERRUPTED - UNKNOWN - SKIPPED - DRAFT - ACTIVE - ARCHIVED - SUSPENDED title: TaskStatusEnum description: |- Enumeration of task statuses for tracking asynchronous operations. Task statuses indicate the current state of asynchronous operations like batch processing, object ingestion, clustering, and taxonomy execution. Status Categories: Operation Statuses: Track progress of async operations Lifecycle Statuses: Track entity state (buckets, collections, namespaces) Values: PENDING: Task is queued but has not started processing yet IN_PROGRESS: Task is currently being executed PROCESSING: Task is actively processing data (similar to IN_PROGRESS) COMPLETED: Task finished successfully with no errors COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success) FAILED: Task encountered an error and could not complete CANCELED: Task was manually canceled by a user or system UNKNOWN: Task status could not be determined SKIPPED: Task was intentionally skipped DRAFT: Task is in draft state and not yet submitted ACTIVE: Entity is active and operational (for buckets, collections, etc.) ARCHIVED: Entity has been archived SUSPENDED: Entity has been temporarily suspended Terminal Statuses: COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state. Partial Success Handling: COMPLETED_WITH_ERRORS indicates that the operation completed but some documents/items failed. The task result includes: - List of successful items - List of failed items with error details - Success rate percentage This allows clients to handle partial success scenarios appropriately. Polling Guidance: - Poll tasks in PENDING, QUEUED, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling FilterOperator: type: string enum: - eq - ne - gt - lt - gte - lte - in - nin - contains - starts_with - ends_with - regex - exists - is_null - text - phrase title: FilterOperator description: Supported filter operators across database implementations. DynamicValue: properties: type: type: string const: dynamic title: Type default: dynamic field: type: string title: Field description: >- The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id' examples: - inputs.query_text - filters.AND[0].value type: object required: - field title: DynamicValue description: A value that should be dynamically resolved from the query request. ````