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",
      "error_summary": null,
      "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>"
          ],
          "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",
          "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"
        }
      ],
      "current_tier": 0,
      "total_tiers": 1,
      "dag_tiers": [
        [
          "col_chunks"
        ]
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "total_count": 123
}

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"

​
X-Namespace
string

REQUIRED: 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'

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,
IN_PROGRESS,
PROCESSING,
COMPLETED,
COMPLETED_WITH_ERRORS,
FAILED,
CANCELED,
UNKNOWN,
SKIPPED,
DRAFT,
ACTIVE,
ARCHIVED,
SUSPENDED
​
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

Response

Successful Response

The response model for listing batches.

​
results
BatchModel · object[]
required

A list of batches.

​
total_count
integer
required

The total number of batches found.