Tasks represent asynchronous jobs in Mixpeek (e.g., batch submissions, extraction runs). Use tasks to track status, progress, and results without blocking requests.
Overview
- What they are: Records of long-running operations (ingestion, enrichment, clustering, etc.).
- When created: Automatically when you submit batches or trigger other long-running operations.
- How used: Poll or list tasks to monitor execution; optionally cancel when supported.
Lifecycle
1
Created
The task is created by the API when you start an async operation
2
Queued
Waiting for a worker to pick up
3
Processing
Actively running
4
Completed/Failed/Canceled
Finishes successfully, errors, or is canceled
Statuses (API enum)
- DRAFT: Initial state for draft tasks (e.g., batch created but not submitted)
- PENDING: Accepted and waiting to be picked up (queued)
- IN_PROGRESS: Transitioning to active execution
- PROCESSING: Actively executing the task
- COMPLETED: Finished successfully; results available
- FAILED: Error occurred during execution
- CANCELED: Stopped before completion by user/system
- SKIPPED: Intentionally not executed as part of a larger workflow
- UNKNOWN: State could not be determined
UI/logs may show conceptual states like Created/Queued/Processing. These map roughly to DRAFT/PENDING/PROCESSING in the API enum.
How tasks are created
- Submitting a batch for processing creates a task
- Other long-running routes may also create tasks depending on the operation
Manage tasks
Best practices
- Store task IDs: Keep the returned
task_idfor later checks - Timeouts: Use timeouts/backoff when polling
- Error handling: Handle
FAILEDandCANCELEDstates explicitly - Webhooks: Prefer webhooks for notifications over tight polling