--- title: "Execute Clustering" method: POST path: "/v1/clusters/{cluster_id}/execute" tags: ["Clusters"] --- # Execute Clustering `POST /v1/clusters/{cluster_id}/execute` Execute clustering on a specific cluster. This endpoint: 1. Validates the cluster exists 2. Queues clustering job via Celery 3. Returns task_id immediately (non-blocking) 4. Celery prepares data and submits to Engine 5. Monitor progress via GET /v1/tasks/{task_id} Flow: - API: Receives request - Celery: Fetches documents, creates parquet, uploads to S3 - Engine: Runs Ray job on parquet data - Status: Automatically updates cluster when complete Use GET /v1/clusters/{id}/executions to retrieve results. Optional body (`ExecuteClusterByIdRequest`) accepts a `filters` override that applies to this execution only and is not persisted on the cluster. ## Path parameters - `cluster_id` string, required — Cluster ID to execute ## Request body - ExecuteClusterByIdRequest — Optional body for POST /v1/clusters/{cluster_id}/execute. Lets callers override the cluster's stored filters for a single execution without mutating the cluster definition — useful for per-partition re-runs (e.g., re-clustering one brand without disturbing other partitions). - `mode` 'full' | 'assign' | 'composite' — Execution mode: - full: Run complete clustering pipeline (default) - assign: Incremental assignment — assign new documents to existing cluster centroids without re-clustering. Requires a previous successful execution with centroids. - composite: Cluster centroids from multiple prior executions to create cross-execution cluster groupings. Requires source_execution_ids pointing to completed runs with centroids. - `source_execution_ids` string[], nullable — List of clustering execution run_ids whose centroids will be clustered together (only used when mode='composite'). Each referenced execution must have status='completed' and non-empty centroids. Minimum 2 executions required. - `assignment_threshold` number, nullable — Minimum cosine similarity to assign a document to a cluster (only used when mode='assign'). Documents below this threshold are marked as noise (cluster_id=-1). Range: 0.0-1.0. - `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 - `sample_size` integer, nullable — Optional per-execution document cap. When provided, overrides the cluster's stored sample_size for this execution only. The override is not persisted on the cluster. KMeans supports up to 1M; O(N²) algorithms (HDBSCAN, Spectral, Agglomerative) are capped at 50K by the engine. - `vis_n_components` 2 | 3, nullable — Number of dimensions for visualization coordinates (2 or 3). When 3, the z coordinate is populated for depth-based rendering. - `defer_visualization` boolean, nullable — When True, skip inline UMAP during clustering and compute the scatter coordinates lazily at /visualization time. UMAP is ~90% of the clustering critical path at scale, so this makes large runs complete much faster; the first scatter load pays a one-time bounded cost. The override is not persisted on the cluster. - `layout_stability` 'none' | 'transform' | 'align', nullable — Optional layout-stability override for this execution (LS-5). 'align' registers the new layout onto the previous run's coordinates (default when the cluster stores nothing), 'transform' reuses the previous run's saved projection reducer when compatible, 'none' re-layouts independently. The override is not persisted on the cluster. - `llm_labeling` LLMLabelingInput — Configuration for LLM-based cluster labeling. Supports multiple LLM providers with comprehensive model selection: - OpenAI: GPT-4o, GPT-4o-mini, GPT-4.1, O3-mini (best for quality) - Google: Gemini 2.5 Flash, Gemini 1.5 Flash (best for speed and cost) - Anthropic: Claude 3.5 Sonnet, Claude 3.5 Haiku (best for reasoning) All models are defined as enums and validated at API level. - `enabled` boolean — Whether to generate labels for clusters using LLM. When enabled, clusters will have semantic labels like 'High-Performance Laptops' instead of generic labels like 'Cluster 0'. - `labeling_inputs` LLMLabelingInputInput — Input configuration for LLM-based cluster labeling. Supports flexible input mappings similar to retrievers and buckets, allowing multimodal inputs (text, images, videos, audio) for providers like Gemini that support native multimodal understanding. Examples: # Text-only labeling: LLMLabelingInput(input_mappings=[ InputMapping(input_key="headline", source_type="payload", path="headline"), InputMapping(input_key="description", source_type="payload", path="description") ]) # Multimodal labeling with images: LLMLabelingInput(input_mappings=[ InputMapping(input_key="text", source_type="payload", path="headline"), InputMapping(input_key="image_url", source_type="payload", path="thumbnail_url") ]) # Multimodal with video (for Gemini): LLMLabelingInput(input_mappings=[ InputMapping(input_key="text", source_type="payload", path="description"), InputMapping(input_key="video_url", source_type="payload", path="video_url") ]) - `input_mappings` InputMapping[], required — Flexible input mappings for constructing LLM context. Supports multimodal inputs (text, image_url, video_url, audio_url). Each mapping specifies how to extract data from document payloads. At least one input mapping is required. - `input_key` string, required — Key used in the constructed inputs payload. - `source_type` 'payload' | 'literal' | 'vector' | 'blob' — Where the value for an input should be retrieved from. - `path` string, nullable — Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback. - `override` unknown - `provider` 'openai' | 'google' | 'anthropic' — Supported LLM providers for content generation. Each provider has different strengths, pricing, and multimodal capabilities. Choose based on your use case, performance requirements, and budget. Values: OPENAI: OpenAI GPT models (GPT-4o, GPT-4.1, O3-mini) - Best for: General purpose, vision tasks, structured outputs - Multimodal: Text, images - Performance: Fast (100-500ms), reliable - Cost: Moderate to high ($0.15-$10 per 1M tokens) - Use when: Need high-quality generation with vision support GOOGLE: Google Gemini models (Gemini 3.1 Flash Lite, Gemini 2.5 Pro) - Best for: Fast generation, video understanding, cost-efficiency - Multimodal: Text, images, video, audio, PDFs - Performance: Very fast (50-200ms) - Cost: Low to moderate ($0.075-$0.40 per 1M tokens) - Use when: Need video/audio/PDF support or cost-efficiency ANTHROPIC: Anthropic Claude models (Claude 3.5 Sonnet, Claude 3.5 Haiku) - Best for: Long context, complex reasoning, safety - Multimodal: Text, images - Performance: Moderate (200-800ms) - Cost: Moderate to high ($0.25-$15 per 1M tokens) - Use when: Need long context or complex reasoning Examples: - Use OPENAI for production with structured JSON outputs - Use GOOGLE for video summarization and cost-sensitive workloads - Use ANTHROPIC for complex reasoning with long documents - `model_name` union — REQUIRED when enabled=True. Specific LLM model to use for cluster labeling. All models are defined as enums for type safety. OpenAI Models (provider='openai'): - gpt-4o-2024-08-06: Highest quality, best for production ($2.50/$10 per 1M tokens) - gpt-4o-mini-2024-07-18: Cost-effective, recommended for most use cases ($0.15/$0.60 per 1M tokens) - gpt-4.1-2025-04-14: Latest model, future-proofed - gpt-4.1-mini-2025-04-14: Latest cost-optimized model - o3-mini-2025-01-31: Advanced reasoning, best for complex clustering Google Models (provider='google'): - gemini-2.5-flash-lite: Fastest, latest multimodal model, recommended ($0.15/$0.60 per 1M tokens) Anthropic Models (provider='anthropic'): - claude-3-5-sonnet-20241022: Best reasoning, 200K context ($3/$15 per 1M tokens) - claude-3-5-haiku-20241022: Fast, cost-effective ($0.25/$1.25 per 1M tokens) Recommendation: - Use gemini-2.5-flash-lite (DEFAULT) - multimodal support - Use gpt-4o-mini-2024-07-18 for OpenAI compatibility - Use gpt-4o-2024-08-06 for highest quality when cost is not a concern - 'gpt-4o-2024-08-06' | 'gpt-4o-mini-2024-07-18' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'o3-mini-2025-01-31' — OpenAI model identifiers for LLM generation. Models listed in order of capability and cost (highest to lowest). All models support vision (images) except O3-mini. Values: GPT_4O: Latest GPT-4 Omni model (2024-08-06) - Use for: Production, highest quality generation - Context: 128K tokens - Vision: Yes - Cost: $2.50/1M input, $10/1M output - Performance: 200-500ms per request - When to use: Need best quality, willing to pay premium GPT_41: GPT-4.1 (2025-04-14) - Use for: Future-proofed pipelines - Context: 128K tokens - Vision: Yes - Cost: TBD (expected similar to GPT-4o) - When to use: Want latest model features GPT_4O_MINI: Smaller, faster GPT-4 Omni (2024-07-18) - Use for: High-volume, cost-sensitive workloads - Context: 128K tokens - Vision: Yes - Cost: $0.15/1M input, $0.60/1M output - Performance: 100-200ms per request - When to use: Good balance of quality and cost GPT_41_MINI: Smaller GPT-4.1 (2025-04-14) - Use for: Future cost-optimized pipelines - Context: 128K tokens - Vision: Yes - Cost: TBD (expected similar to GPT-4o-mini) - When to use: Want latest features at lower cost O3_MINI: Reasoning-optimized model (2025-01-31) - Use for: Complex reasoning, math, code - Context: 200K tokens - Vision: No - Cost: TBD - When to use: Need advanced reasoning capabilities Examples: - Use GPT_4O for caption generation with images (best quality) - Use GPT_4O_MINI for high-volume video scene summarization (cost-effective) - Use O3_MINI for complex entity extraction requiring reasoning - 'gemini-2.5-flash-lite' | 'gemini-2.5-flash' | 'gemini-2.5-pro' | 'gemini-3.1-flash-lite' — Google Gemini model identifiers for LLM generation. Gemini models excel at multimodal understanding with best-in-class video support. All models support text, images, video, audio, and PDFs. Values: GEMINI_2_5_FLASH_LITE: Gemini 2.5 Flash Lite model (recommended, stable GA) - Use for: Fastest generation, cost-effective multimodal - Context: 1M tokens - Multimodal: Text, images, video, audio, PDFs - When to use: Default choice for all Gemini use cases GEMINI_2_5_PRO: Gemini 2.5 Pro model - Use for: Higher quality reasoning, complex tasks - Context: 1M tokens GEMINI_2_5_FLASH: Gemini 2.5 Flash model - Kept for backward compatibility. GEMINI_3_1_FLASH_LITE: Alias for gemini-2.5-flash-lite (backwards compat) - Note: gemini-3.1-flash-lite does NOT exist in Google's API. This value is mapped to gemini-2.5-flash-lite at runtime. - 'claude-sonnet-4-5-20250929' | 'claude-haiku-4-5-20251001' | 'claude-3-5-sonnet-20241022' | 'claude-3-5-haiku-20241022' — Anthropic Claude model identifiers for LLM generation. Claude models excel at long context, complex reasoning, and safety. All models support text and images. Values: CLAUDE_3_5_SONNET: Most capable Claude model - Use for: Complex reasoning, long documents, safety-critical - Context: 200K tokens - Vision: Yes - Cost: $3/1M input, $15/1M output - Performance: 300-800ms per request - When to use: Need best reasoning, safety, or long context CLAUDE_3_5_HAIKU: Fast, cost-effective Claude model - Use for: High-volume, quick summaries - Context: 200K tokens - Vision: Yes - Cost: $0.25/1M input, $1.25/1M output - Performance: 100-300ms per request - When to use: Good balance of quality and cost Examples: - Use CLAUDE_3_5_SONNET for complex entity extraction from contracts (best reasoning) - Use CLAUDE_3_5_HAIKU for high-volume content moderation (cost-effective) - `include_summary` boolean — Whether to generate cluster summaries - `include_keywords` boolean — Whether to extract keywords for clusters - `max_samples_per_cluster` integer, nullable — Maximum representative documents to send to LLM per cluster for semantic analysis. When null (default), automatically scales based on cluster size and spread — smaller/tighter clusters get fewer samples, larger/sparser clusters get more (range 3-20). Set explicitly to override with a fixed value. - `sample_text_max_length` integer — Maximum characters per document sample text - `sample_selection_strategy` 'nearest' | 'representative' — How representative documents are chosen for the labeling LLM. 'nearest' (default): the N members closest to the cluster centroid — maximally prototypical, but adjacent clusters can yield near-identical sample sets and therefore near-identical labels. 'representative': a mixed panel of ~40% nearest-to-centroid, ~40% diversity picks (farthest-point coverage of the cluster's extent), and ~20% high-density examples — differentiates similar clusters at the same sample count and LLM cost. - `use_embedding_dedup` boolean — Enable embedding-based label deduplication to prevent near-duplicate labels (requires sentence-transformers) - `embedding_similarity_threshold` number — Cosine similarity threshold for duplicate label detection (labels above this are considered duplicates) - `cache_ttl_seconds` integer — Time-to-live for cached labels in seconds. Labels for clusters with identical representative documents will be reused within this TTL window, reducing LLM API costs. Default: 604800 (7 days). Set to 0 to disable caching. - `labeling_context` string, nullable — OPTIONAL. Freeform domain context about the data being clustered, injected into the labeling prompt as a clearly-delimited 'Domain context provided by the user' block (LS-4). Unlike custom_prompt, this does NOT replace the default prompt — it grounds the default labeler so labels use the right domain vocabulary. Example: 'These are scenes from pharmaceutical TV ads' turns generic labels like 'People Talking Outdoors' into 'Patient Testimonial Scenes'. Max 2000 characters. - `custom_prompt` string, nullable — OPTIONAL. Custom prompt template for LLM labeling. NOT REQUIRED - uses default discriminative prompt if not provided. When provided, completely replaces the default prompt. Your custom prompt receives cluster information but you must format it yourself. Use when: - Need domain-specific labeling (e.g., medical, legal, technical) - Want different label format (e.g., emoji labels, code names) - Require specific output structure - Have custom business logic for categorization Default prompt includes: cluster document samples, forbidden labels for uniqueness, and JSON response format. See engine/clusters/labeling/prompts.py for reference. Example: 'Analyze these product clusters and generate SHORT category names (2-3 words max) focusing on product type and price range. Return JSON: [{"cluster_id": "cl_0", "label": "..."}]' - `response_shape` union — OPTIONAL. Define custom structured output for LLM labeling. NOT REQUIRED - uses default structure (label, summary, keywords) if not provided. When provided, LLM output will match this structure and be stored in cluster documents. Two modes supported: 1. Natural language prompt (string): Describe desired output in plain English - Service automatically infers JSON schema from your description - Example: 'Extract cluster category, confidence score (0-1), and top 3 representative terms' - Auto-generates schema with appropriate types (string, number, array, etc.) 2. Explicit JSON schema (dict): Provide complete JSON schema for output structure - Full control over output structure, types, and constraints - Example: {'type': 'object', 'properties': {'category': {'type': 'string'}, ...}} Use when: - Need custom metadata fields (confidence scores, sentiment, complexity) - Want domain-specific structure (taxonomy hierarchies, entity extractions) - Require specific data types (arrays, nested objects, enums) - Have downstream schema requirements Output fields are automatically added to cluster collection schema and stored in metadata. Default behavior (if not provided): label (string), summary (string), keywords (array of strings) - string - object - `parameters` object — Provider-specific parameters forwarded to the LLM service. For OpenAI: temperature, max_tokens, top_p, json_output, etc. For Google: temperature, top_k, max_output_tokens, json_output, etc. ## Response `200` Successful Response - TaskResponse — Task response model returned by the API. Extends TaskModel with additional convenience fields for API responses. This is the model returned when you GET /v1/tasks/{task_id}. Additional Fields: error_message: Convenience field that surfaces errors from additional_data for easier error handling in client code. Inheritance: Inherits all fields and documentation from TaskModel, including: - task_id: Unique identifier - task_type: Operation type - status: Current status - inputs: Input parameters - outputs: Output results - additional_data: Metadata and context Storage Architecture: Same as TaskModel - stored in Redis (24hr TTL) with MongoDB fallback. Usage: This model is automatically returned by task API endpoints. You don't need to construct it manually - just call GET /v1/tasks/{task_id}. Error Handling: Check the error_message field for a user-friendly error string, or additional_data['error'] for the full error details. Example Response: { "task_id": "task_abc123", "task_type": "api_buckets_batches_process", "status": "FAILED", "inputs": ["batch_xyz"], "outputs": null, "additional_data": { "error": "Failed to process batch: Object not found", "batch_id": "batch_xyz" }, "error_message": "Failed to process batch: Object not found" } - `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. ## 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/220a3b263fda/schema)