--- title: "List Tasks" method: POST path: "/v1/tasks/list" tags: ["Tasks"] --- # List Tasks `POST /v1/tasks/list` List tasks with optional filtering, sorting, and pagination. **Filter Options**: - `status`: Filter by specific status (PENDING, IN_PROGRESS, COMPLETED, FAILED, etc.) - `task_type`: Filter by task type **Examples**: - All tasks: `{}` - Failed tasks only: `{"status": "FAILED"}` - Pending batches: `{"status": "PENDING", "task_type": "API_BUCKETS_UPLOADS_BATCH_CONFIRM"}` - In-progress tasks: `{"status": "IN_PROGRESS"}` ## 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 - ListTasksRequest — Request model for listing tasks. Filter tasks by status, type, or other criteria. - `status` 'PENDING' | 'QUEUED' | 'IN_PROGRESS' | 'PROCESSING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELED' | 'INTERRUPTED' | 'UNKNOWN' | 'SKIPPED' | 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'SUSPENDED' | 'DEACTIVATED' — 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 - `task_type` 'api_namespaces_create' | 'api_namespaces_delete' | 'api_namespaces_snapshot_create' | 'api_namespaces_snapshot_restore' | 'api_namespaces_migrations_run' | 'api_buckets_objects_create' | 'api_buckets_delete' | 'api_buckets_batches_process' | 'api_buckets_batches_submit' | 'api_buckets_uploads_create' | 'api_buckets_uploads_confirm' | 'api_buckets_uploads_batch_confirm' | 'api_collections_documents_create' | 'api_collections_extraction_artifacts' | 'api_taxonomies_create' | 'api_taxonomies_execute' | 'api_taxonomies_materialize' | 'api_evaluations_run' | 'api_evaluations_dataset_create' | 'api_retrievers_publish' | 'api_collections_export' | 'api_collections_trigger' | 'engine_feature_extractor_run' | 'engine_inference_run' | 'engine_object_processing' | 'engine_cluster_build' | 'thumbnail' | 'video_segment' | 'audio_segment' | 'converted_video' | 'materialize' | 'plugin_custom' | 'model_custom' — Types of asynchronous tasks that can be performed in the system. Task types identify the specific operation being performed. This helps with tracking, debugging, and filtering tasks by operation type. Categories: API Tasks: User-initiated operations via API endpoints Engine Tasks: Background processing tasks Inference Tasks: Specialized inference operations API Task Types: API_NAMESPACES_CREATE: Creating a new namespace API_NAMESPACES_MIGRATIONS_RUN: Running a namespace migration API_BUCKETS_OBJECTS_CREATE: Creating objects in a bucket API_BUCKETS_DELETE: Deleting a bucket and its contents API_BUCKETS_BATCHES_PROCESS: Processing a batch of objects API_BUCKETS_BATCHES_SUBMIT: Submitting a batch for processing API_BUCKETS_UPLOADS_CREATE: Creating an upload session API_BUCKETS_UPLOADS_CONFIRM: Confirming an upload completion API_BUCKETS_UPLOADS_BATCH_CONFIRM: Confirming batch upload completion API_TAXONOMIES_CREATE: Creating a new taxonomy API_TAXONOMIES_EXECUTE: Executing taxonomy classification API_TAXONOMIES_MATERIALIZE: Materializing taxonomy results API_RETRIEVERS_PUBLISH: Publishing retriever assets (OG images, etc.) Engine Task Types: ENGINE_FEATURE_EXTRACTOR_RUN: Running feature extraction on data ENGINE_INFERENCE_RUN: Running inference operations ENGINE_OBJECT_PROCESSING: Processing object data ENGINE_CLUSTER_BUILD: Building clusters from data Inference Task Types: THUMBNAIL: Generating thumbnails MATERIALIZE: Materializing processed data Usage: Task types are automatically assigned when tasks are created. You can filter tasks by type when listing or searching for specific operations. - `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' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `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' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `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' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `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 — Search term. ## Response `200` Successful Response - ListTasksResponse — Response model for listing tasks. - `results` TaskResponse[], required - `task_id` string, required — Unique identifier for the task. REQUIRED. Used to poll task status via GET /v1/tasks/{task_id}. This ID is also stored on parent resources (batches, clusters, etc.) for cross-referencing. Format: UUID v4 or custom string identifier. - `task_type` 'api_namespaces_create' | 'api_namespaces_delete' | 'api_namespaces_snapshot_create' | 'api_namespaces_snapshot_restore' | 'api_namespaces_migrations_run' | 'api_buckets_objects_create' | 'api_buckets_delete' | 'api_buckets_batches_process' | 'api_buckets_batches_submit' | 'api_buckets_uploads_create' | 'api_buckets_uploads_confirm' | 'api_buckets_uploads_batch_confirm' | 'api_collections_documents_create' | 'api_collections_extraction_artifacts' | 'api_taxonomies_create' | 'api_taxonomies_execute' | 'api_taxonomies_materialize' | 'api_evaluations_run' | 'api_evaluations_dataset_create' | 'api_retrievers_publish' | 'api_collections_export' | 'api_collections_trigger' | 'engine_feature_extractor_run' | 'engine_inference_run' | 'engine_object_processing' | 'engine_cluster_build' | 'thumbnail' | 'video_segment' | 'audio_segment' | 'converted_video' | 'materialize' | 'plugin_custom' | 'model_custom', required — Types of asynchronous tasks that can be performed in the system. Task types identify the specific operation being performed. This helps with tracking, debugging, and filtering tasks by operation type. Categories: API Tasks: User-initiated operations via API endpoints Engine Tasks: Background processing tasks Inference Tasks: Specialized inference operations API Task Types: API_NAMESPACES_CREATE: Creating a new namespace API_NAMESPACES_MIGRATIONS_RUN: Running a namespace migration API_BUCKETS_OBJECTS_CREATE: Creating objects in a bucket API_BUCKETS_DELETE: Deleting a bucket and its contents API_BUCKETS_BATCHES_PROCESS: Processing a batch of objects API_BUCKETS_BATCHES_SUBMIT: Submitting a batch for processing API_BUCKETS_UPLOADS_CREATE: Creating an upload session API_BUCKETS_UPLOADS_CONFIRM: Confirming an upload completion API_BUCKETS_UPLOADS_BATCH_CONFIRM: Confirming batch upload completion API_TAXONOMIES_CREATE: Creating a new taxonomy API_TAXONOMIES_EXECUTE: Executing taxonomy classification API_TAXONOMIES_MATERIALIZE: Materializing taxonomy results API_RETRIEVERS_PUBLISH: Publishing retriever assets (OG images, etc.) Engine Task Types: ENGINE_FEATURE_EXTRACTOR_RUN: Running feature extraction on data ENGINE_INFERENCE_RUN: Running inference operations ENGINE_OBJECT_PROCESSING: Processing object data ENGINE_CLUSTER_BUILD: Building clusters from data Inference Task Types: THUMBNAIL: Generating thumbnails MATERIALIZE: Materializing processed data Usage: Task types are automatically assigned when tasks are created. You can filter tasks by type when listing or searching for specific operations. - `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 - `inputs` union[], nullable — Input parameters or data used to start the task. OPTIONAL. May include IDs, configuration objects, or file references. Useful for debugging and understanding what data the task processed. Format: List of strings (IDs) or objects (configuration). Example: ['batch_id_123'] or [{'bucket_id': 'bkt_abc', 'config': {...}}] - union - string - object - `outputs` union[], nullable — Output results produced by the task. OPTIONAL. Populated when task completes successfully. May include processed file IDs, result metrics, or status summaries. Check this field after task reaches COMPLETED status to get results. Format: List of strings (output IDs) or objects (result data). - union - string - object - `additional_data` object, nullable — Additional metadata and context for the task. OPTIONAL. Contains job IDs, error details, progress info, and other task-specific metadata. Common fields (all task types): - 'error': Error message if task failed - 'job_id': Ray job ID for engine tasks - 'from_mongodb': True if retrieved from MongoDB fallback (not Redis) Batch-specific fields (task_type=api_buckets_batches_process): - 'batch_id': Batch identifier (REQUIRED) - 'bucket_id': Source bucket identifier (REQUIRED) - 'namespace_id': Namespace identifier (REQUIRED) - 'current_tier': Currently processing tier number, 0-indexed (OPTIONAL, None if not started) - 'total_tiers': Total number of tiers in the batch pipeline (REQUIRED) - 'collection_ids': Array of ALL collection IDs across all tiers (REQUIRED) - 'object_count': Number of objects being processed (REQUIRED) - 'sample_object_ids': First 5 object IDs for debugging/display (OPTIONAL) Performance Note: Full object_ids array is NOT stored in task metadata to avoid bloating task documents (batches with 10k+ objects would add 200KB+ per task). For full object list, query the batch directly via GET /v1/buckets/{bucket_id}/batches/{batch_id}. Note: For detailed per-tier status, use GET /v1/buckets/{bucket_id}/batches/{batch_id} to access the tier_tasks[] array which contains individual tier statuses, collection_ids, and timestamps for each tier. - `error` string, nullable — Flattened error message for convenient error handling. OPTIONAL. Automatically populated from additional_data['error'] when the task has FAILED status. This is a convenience field - the full error details are always available in additional_data['error']. Use this field for displaying errors to users or logging. Will be None if task has not failed or if no error details are available. Serialized as 'error' in API responses for backward compatibility. - `queue_position` integer, nullable — 1-based position in the Ray processing waitlist. None if the batch was dispatched immediately (no queue). Position 1 means this batch will be processed next. - `estimated_wait_minutes` number, nullable — Estimated minutes until this batch starts processing, based on queue position and average batch duration. None if the batch was dispatched immediately. - `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 - `page` integer, nullable - `page_size` integer, nullable - `total_pages` integer, nullable - `next_page` string, nullable - `previous_page` string, nullable - `next_cursor` string, nullable ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error --- [API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/23e05292e326/schema)