Skip to main content
POST
/
v1
/
tasks
/
list
List Tasks
curl --request POST \
  --url https://api.mixpeek.com/v1/tasks/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "PENDING",
  "task_type": "api_namespaces_create",
  "filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "sort": {
    "field": "created_at",
    "direction": "desc"
  },
  "search": "<string>"
}'
{
  "results": [
    {
      "additional_data": {
        "batch_id": "btch_xyz789",
        "bucket_id": "bkt_products",
        "collection_ids": [
          "col_tier0",
          "col_tier1",
          "col_tier2"
        ],
        "current_tier": 1,
        "job_id": "ray_job_123",
        "namespace_id": "ns_abc123",
        "object_count": 10000,
        "sample_object_ids": [
          "obj_001",
          "obj_002",
          "obj_003",
          "obj_004",
          "obj_005"
        ],
        "total_tiers": 3
      },
      "description": "Multi-tier batch processing task in progress (tier 1 of 3) with 10k objects",
      "inputs": [
        "batch_xyz789"
      ],
      "status": "IN_PROGRESS",
      "task_id": "2d322a05-3178-4eca-aac6-b82b0a0313aa",
      "task_type": "api_buckets_batches_process"
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

Query Parameters

​
limit
integer | null
​
offset
integer | null

Body

application/json

Request model for listing tasks.

Filter tasks by status, type, or other criteria.

​
status
enum<string> | null

Filter by specific task status (PENDING, IN_PROGRESS, PROCESSING, COMPLETED, FAILED, CANCELED, etc.). 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, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling

Available options:
PENDING,
IN_PROGRESS,
PROCESSING,
COMPLETED,
COMPLETED_WITH_ERRORS,
FAILED,
CANCELED,
UNKNOWN,
SKIPPED,
DRAFT,
ACTIVE,
ARCHIVED,
SUSPENDED
​
task_type
enum<string> | null

Filter by task type (e.g., API_BUCKETS_OBJECTS_CREATE, BATCH_CONFIRM, etc.) 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_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

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.

Available options:
api_namespaces_create,
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_taxonomies_create,
api_taxonomies_execute,
api_taxonomies_materialize,
engine_feature_extractor_run,
engine_inference_run,
engine_object_processing,
engine_cluster_build,
thumbnail,
video_segment,
materialize
​
filters
object | null

Advanced filters to apply. 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"}).

​
sort
object | null

Sort options. Specifies how to sort query results.

Attributes: field: Field to sort by direction: Sort direction (ascending or descending)

​
search
string | null

Search term.

Response

Successful Response

Response model for listing tasks.

​
results
TaskResponse · object[]
required
​
pagination
object
required

PaginationResponse.