--- title: "List Uploads" method: POST path: "/v1/buckets/{bucket_identifier}/uploads/list" tags: ["Bucket Uploads"] --- # List Uploads `POST /v1/buckets/{bucket_identifier}/uploads/list` ## Request - Base URL: `https://api.mixpeek.com` - URL: `https://api.mixpeek.com/v1/buckets/{bucket_identifier}/uploads/list` - Auth: HTTP bearer and API key in header `X-Namespace` 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` ## Path parameters - `bucket_identifier` string, required: The unique identifier of the bucket ## Query parameters - `limit` integer, nullable - `page_size` integer, nullable - `offset` integer, nullable - `page` integer, nullable - `cursor` string, nullable - `next_cursor` string, nullable - `after` string, nullable - `include_total` boolean ## Request body - ListUploadsRequest: 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` LogicalOperatorInput: 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"}). - `AND` union[], nullable: Logical AND operation - all conditions must be true - union - LogicalOperatorInput (recursive) - FilterCondition: Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required: Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'words' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon': Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem. - `value` union, required: Value to compare against - DynamicValue: A value that should be dynamically resolved from the query request. - … - unknown - `OR` union[], nullable: Logical OR operation - at least one condition must be true - union - LogicalOperatorInput (recursive) - FilterCondition: Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required: Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'words' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon': Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem. - `value` union, required: Value to compare against - DynamicValue: A value that should be dynamically resolved from the query request. - … - unknown - `NOT` union[], nullable: Logical NOT operation - all conditions must be false - union - LogicalOperatorInput (recursive) - FilterCondition: Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required: Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'words' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon': Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem. - `value` union, required: Value to compare against - DynamicValue: A value that should be dynamically resolved from the query request. - … - unknown - `case_sensitive` boolean, nullable: Whether to perform case-sensitive matching - `sort` SortOption: Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending) - `field` string, required: Field to sort by, supports dot notation for nested fields - `direction` 'asc' | 'desc': Sort direction options. - `search` string, 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_urls` boolean: 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: Maximum number of uploads to return. OPTIONAL, defaults to 20. - `offset` integer: Number of uploads to skip for pagination. OPTIONAL, defaults to 0. ## Response `200` Successful Response - ListUploadsResponse: Response model for listing uploads. - `results` UploadResponse[], required: List of upload records matching the query - `upload_id` string, required: 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. - `bucket_id` string, required: Target bucket ID where object will be created - `filename` string, required: Name of the file to upload - `content_type` string, required: MIME type enforced by the presigned URL - `file_size_bytes` integer, nullable: Expected file size in bytes if provided in request. Will be validated during confirmation. - `presigned_url` string, uri, nullable: 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` integer, required: How long the presigned URL is valid, in seconds - `s3_key` string, required: 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. - `status` 'PENDING' | 'QUEUED' | 'IN_PROGRESS' | 'PROCESSING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELED' | 'INTERRUPTED' | 'UNKNOWN' | 'SKIPPED' | 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'SUSPENDED' | 'DEACTIVATED', required: 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 - `metadata` object: Custom metadata for tracking - `create_object_on_confirm` boolean, required: Whether bucket object will be auto-created on confirmation - `object_metadata` object, nullable: Metadata for the bucket object (if create_object_on_confirm=true) - `blob_property` string, nullable: Property name for the blob in bucket object - `blob_type` string, nullable: Type of blob (IMAGE, VIDEO, etc.) - `file_hash` string, nullable: SHA256 hash of the file content. Set during confirmation from S3 metadata or provided in request. Used for duplicate detection. - `skip_duplicates` boolean: Whether duplicate detection was enabled for this upload - `is_duplicate` boolean: 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. - `duplicate_of_upload_id` string, nullable: 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. - `skipped_unique_key` boolean: 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. - `existing_object_id` string, nullable: 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. - `message` string, nullable: Human-readable message about the upload. When status is FAILED, the reason it failed (for example it was not confirmed before expires_at, or its confirmation did not finish). Also 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` string, date-time, required: When this upload record was created (ISO 8601 format) - `expires_at` string, date-time, required: 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) - `completed_at` string, date-time, nullable: When the upload was completed and verified (ISO 8601 format) - `verified_at` string, date-time, nullable: When S3 object existence was verified (ISO 8601 format) - `etag` string, nullable: S3 ETag from the uploaded object (set during confirmation) - `object_id` string, nullable: Created bucket object ID (if create_object_on_confirm was true) - `task_id` string, nullable: Task ID for async confirmation (if processed asynchronously) - `pagination` PaginationResponse, required: PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true - `total` integer, nullable: Number of items matching the request across all pages, filters included. null unless the request set include_total=true (in the body or as ?include_total=true). A counted request that matches nothing returns 0. - `page` integer, nullable - `page_size` integer, nullable - `total_pages` integer, nullable: Number of pages at page_size. null unless include_total=true. - `next_page` string, nullable - `previous_page` string, nullable - `next_cursor` string, nullable - `stats` UploadListStats, required: Aggregate statistics for a list of uploads. - `total_uploads` integer, required: Total number of uploads in the result set - `total_size_bytes` integer, required: Total size of all files in bytes - `uploads_by_status` object, required: Count of uploads grouped by status - `avg_file_size_bytes` number, required: Average file size across all uploads - `unique_buckets` integer, required: Number of unique buckets in the result set ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `422`: Unprocessable Entity - `429`: Too Many Requests - `500`: Internal Server Error - `503`: Service Unavailable ## Changes - **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info - removed the optional property `detail` from the response with the `422` status - added the non-success response with the status `429` - added the non-success response with the status `503` - added the optional property `success` to the response with the `422` status - …2 more - **2026-09-26** `5231c1d891e8`: 3 info - added the new `words` enum value to the request property `filters/anyOf[subschema #1: LogicalOperator]/AND/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator` - added the new `words` enum value to the request property `filters/anyOf[subschema #1: LogicalOperator]/NOT/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator` - added the new `words` enum value to the request property `filters/anyOf[subschema #1: LogicalOperator]/OR/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator` - **2026-08-09** `5d4c905106b4`: 1 info - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API - **2026-08-04** `9603dfdab463`: 1 warning - added the new `DEACTIVATED` enum value to the `results/items/status` response property for the response status `200` - **2026-08-02** `72cc17ba6f7f`: 2 info - added the new optional `query` request parameter `after` - added the new optional `query` request parameter `next_cursor` [Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/buckets/:bucket_identifier/uploads/list/post.md) --- [API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)