Skip to main content
POST
/
v1
/
batches
/
list
List All Batches
curl --request POST \
  --url https://api.mixpeek.com/v1/batches/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "offset": 0,
  "limit": 100
}
'
import requests

url = "https://api.mixpeek.com/v1/batches/list"

payload = {
    "offset": 0,
    "limit": 100
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({offset: 0, limit: 100})
};

fetch('https://api.mixpeek.com/v1/batches/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/batches/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'offset' => 0,
    'limit' => 100
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/batches/list"

	payload := strings.NewReader("{\n  \"offset\": 0,\n  \"limit\": 100\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/batches/list")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offset\": 0,\n  \"limit\": 100\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/batches/list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offset\": 0,\n  \"limit\": 100\n}"

response = http.request(request)
puts response.read_body
{
  "results": [
    {
      "bucket_id": "<string>",
      "batch_id": "<string>",
      "namespace_id": "<string>",
      "status": "DRAFT",
      "object_ids": [
        "<string>"
      ],
      "dedup_strategy": "skip",
      "submitted_by_key_id": "<string>",
      "submitted_by_key_prefix": "<string>",
      "submitted_by_is_internal": true,
      "dedup_audit": {},
      "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>",
          "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": {
        "campaign_id": "Q4_2025",
        "source": "s3://raw-uploads/2026-05/",
        "tags": [
          "video",
          "high-priority"
        ],
        "notes": "Re-run after Whisper quota fix"
      },
      "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>"
              ],
              "extractor_id": "universal_extractor_v1",
              "ray_job_id": "raysubmit_abc123",
              "celery_task_id": "celery_task_abc123",
              "callback_job_id": "celery_fast_path_btch_abc123_0_universal_extractor_v1",
              "execution_mode": "celery_fast_path_universal",
              "status": "PENDING",
              "started_at": "2023-11-07T05:31:56Z",
              "completed_at": "2023-11-07T05:31:56Z",
              "duration_ms": 123,
              "documents_written": 123,
              "pages_dropped": 10,
              "pages_dropped_reasons": {
                "max_document_pages_cap": 10
              },
              "documents_skipped": 0,
              "errors": [
                {
                  "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",
              "submission_params": {
                "entrypoint": "<string>",
                "deployment_mode": "<string>",
                "requires_gpu": true,
                "num_cpus": 123,
                "num_gpus": 123,
                "memory_bytes": 123,
                "priority": 123,
                "plugin_archives": [
                  "<string>"
                ],
                "plugin_dependencies": [
                  "<string>"
                ],
                "image_uri": "<string>",
                "extractor_name": "<string>",
                "extractor_version": "<string>",
                "env_vars_keys": [
                  "<string>"
                ],
                "manifest_key": "<string>",
                "submitted_at": "2023-11-07T05:31:56Z"
              }
            }
          ],
          "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": [
            {
              "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",
          "ray_job_logs": "<string>",
          "ray_job_logs_captured_at": "2023-11-07T05:31:56Z",
          "submission_params": {
            "entrypoint": "<string>",
            "deployment_mode": "<string>",
            "requires_gpu": true,
            "num_cpus": 123,
            "num_gpus": 123,
            "memory_bytes": 123,
            "priority": 123,
            "plugin_archives": [
              "<string>"
            ],
            "plugin_dependencies": [
              "<string>"
            ],
            "image_uri": "<string>",
            "extractor_name": "<string>",
            "extractor_version": "<string>",
            "env_vars_keys": [
              "<string>"
            ],
            "manifest_key": "<string>",
            "submitted_at": "2023-11-07T05:31:56Z"
          },
          "infrastructure_events": [
            {
              "detected_at": "2023-11-07T05:31:56Z",
              "raw_signal": "<string>",
              "node_id": "<string>",
              "pod_name": "<string>"
            }
          ],
          "audit": {},
          "audit_override_reason": "<string>"
        }
      ],
      "current_tier": 0,
      "total_tiers": 1,
      "dag_tiers": [
        [
          "col_chunks"
        ]
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "progress": null,
      "documents_written": null,
      "pages_dropped": null,
      "pages_dropped_reasons": null,
      "status_diagnostics": {},
      "health": "healthy",
      "cost": {
        "credits_consumed": 0,
        "cost_usd": 0,
        "credit_rate_usd": 0.001
      },
      "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": {}
}
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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,
INTERRUPTED,
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 | null

Pagination metadata including next_cursor for deep pagination.