Skip to main content
POST
/
v1
/
buckets
/
{bucket_identifier}
/
batches
/
list
List Batches
curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/batches/list \
  --header 'Content-Type: application/json' \
  --data '
{
  "offset": 0,
  "limit": 100
}
'
{
  "results": [
    {
      "bucket_id": "<string>",
      "batch_id": "<string>",
      "status": "DRAFT",
      "object_ids": [
        "<string>"
      ],
      "collection_ids": [
        "col_chunks"
      ],
      "error": "Failed to process batch: Object not found",
      "failure_reason": "Ray job failed: ImportError: No module named 'google.genai'",
      "error_summary": null,
      "failure_category": null,
      "failed_objects": [
        {
          "object_id": "<string>",
          "error": "<string>",
          "error_type": "transient",
          "timestamp": "<string>"
        }
      ],
      "failed_object_count": 0,
      "type": "BUCKET",
      "manifest_key": "ns_abc/org_123/manifests/tier_0.parquet",
      "task_id": "task_tier0_abc123",
      "loaded_object_ids": [
        "obj_video_001",
        "obj_video_002"
      ],
      "internal_metadata": {
        "include_history": true,
        "last_health_check": {
          "enriched_documents": 98,
          "health_status": "HEALTHY",
          "missing_features": [
            "text_embedding"
          ],
          "processed_documents": 100,
          "recommendations": [],
          "stall_duration_seconds": 0,
          "timestamp": "2025-11-06T10:05:00Z",
          "total_documents": 100,
          "vector_populated_count": 98
        }
      },
      "metadata": {},
      "tier_tasks": [
        {
          "tier_num": 1,
          "source_type": "<string>",
          "task_id": "task_tier0_abc123",
          "status": "PENDING",
          "collection_ids": [
            "<string>"
          ],
          "extractor_jobs": [
            {
              "extractor_type": "<string>",
              "collection_ids": [
                "<string>"
              ],
              "ray_job_id": "raysubmit_abc123",
              "celery_task_id": "celery_task_abc123",
              "status": "PENDING",
              "started_at": "2023-11-07T05:31:56Z",
              "completed_at": "2023-11-07T05:31:56Z",
              "duration_ms": 123,
              "documents_written": 123,
              "errors": [
                {
                  "error_type": "dependency",
                  "message": "<string>",
                  "component": "VertexMultimodalService",
                  "stage": "gemini_extraction",
                  "traceback": "<string>",
                  "timestamp": "2023-11-07T05:31:56Z",
                  "affected_document_ids": [
                    "<string>"
                  ],
                  "affected_count": 1,
                  "recovery_suggestion": "Install google-genai package: pip install google-genai",
                  "metadata": {}
                }
              ],
              "error": "Ray job FAILED",
              "last_activity_at": "2023-11-07T05:31:56Z",
              "ray_job_status": "RUNNING"
            }
          ],
          "source_collection_ids": [
            "col_chunks"
          ],
          "parent_task_id": "task_tier0_abc123",
          "started_at": "2025-11-03T10:00:00Z",
          "completed_at": "2025-11-03T10:05:00Z",
          "duration_ms": 300000,
          "errors": [
            {
              "error_type": "dependency",
              "message": "<string>",
              "component": "VertexMultimodalService",
              "stage": "gemini_extraction",
              "traceback": "<string>",
              "timestamp": "2023-11-07T05:31:56Z",
              "affected_document_ids": [
                "<string>"
              ],
              "affected_count": 1,
              "recovery_suggestion": "Install google-genai package: pip install google-genai",
              "metadata": {}
            }
          ],
          "error_summary": null,
          "performance": {
            "avg_latency_ms": 234.56,
            "bottlenecks": [
              {
                "avg_time_ms": 113.58,
                "execution_count": 50,
                "max_time_ms": 234.56,
                "stage_name": "gcs_batch_upload_all_segments",
                "total_time_ms": 5678.9
              },
              {
                "avg_time_ms": 69.14,
                "execution_count": 50,
                "max_time_ms": 123.45,
                "stage_name": "pipeline_run",
                "total_time_ms": 3456.78
              }
            ],
            "stage_count": 5,
            "timestamp": "2025-11-06T10:05:00Z",
            "total_time_ms": 12345.67
          },
          "ray_job_id": "raysubmit_9pDAyZbd5MN281TB",
          "requires_gpu": null,
          "worker_groups": null,
          "celery_task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "source_documents_fetched": 100,
          "documents_after_source_filter": 95,
          "documents_missing_input_fields": 0,
          "documents_submitted_to_engine": 95,
          "documents_written": 95,
          "documents_before_processing": 0,
          "last_activity_at": "2023-11-07T05:31:56Z",
          "ray_job_status": "RUNNING"
        }
      ],
      "current_tier": 0,
      "total_tiers": 1,
      "dag_tiers": [
        [
          "col_chunks"
        ]
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "progress": null,
      "health": "healthy",
      "last_activity_at": "2023-11-07T05:31:56Z",
      "retry_count": 0,
      "max_retries": 3,
      "last_retry_at": null,
      "retry_reason": null,
      "webhook_url": "https://example.com/webhooks/batch-complete",
      "updated_at": "2023-11-07T05:31:56Z",
      "status_message": "<string>",
      "estimated_completion": "2023-11-07T05:31:56Z"
    }
  ],
  "total_count": 123,
  "pagination": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Headers

​
Authorization
string

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 YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

​
authorization
string
​
X-Namespace
string

Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'. Falls back to ?namespace= query parameter if the header is omitted.

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

​
bucket_identifier
string
required

The unique identifier of the bucket.

Body

application/json

The request model for listing batches.

​
status
enum<string> | null

Filter batches by status.

Available options:
PENDING,
QUEUED,
IN_PROGRESS,
PROCESSING,
COMPLETED,
COMPLETED_WITH_ERRORS,
FAILED,
CANCELED,
UNKNOWN,
SKIPPED,
DRAFT,
ACTIVE,
ARCHIVED,
SUSPENDED
​
collection_id
string | null

Filter batches to only those associated with a specific collection ID. Useful for tracking the processing state of all batches for a given collection.

​
bucket_id
string | null

Filter batches to only those belonging to a specific bucket. Useful with the org-level POST /v1/batches/list endpoint to scope results.

​
offset
integer
default:0

The number of batches to skip.

Required range: x >= 0
​
limit
integer
default:100

The maximum number of batches to return.

Required range: 1 <= x <= 1000
​
cursor
string | null

Cursor for deep pagination. Use next_cursor from a previous response to fetch the next page. More efficient than offset for large result sets.

Response

Successful Response

The response model for listing batches.

Each batch in results includes bucket_id, enabling callers to build batch-to-bucket mappings without additional queries.

​
results
BatchModel · object[]
required

A list of batches.

​
total_count
integer
required

The total number of batches found.

​
pagination
Pagination · object

Pagination metadata including next_cursor for deep pagination.