List Batches

curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/batches/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "offset": 0,
  "limit": 100
}
'

import requests

url = "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/batches/list"

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

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

print(response.text)

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

fetch('https://api.mixpeek.com/v1/buckets/{bucket_identifier}/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/buckets/{bucket_identifier}/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",
    "X-Namespace: <api-key>"
  ],
]);

$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/buckets/{bucket_identifier}/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("X-Namespace", "<api-key>")
	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/buckets/{bucket_identifier}/batches/list")
  .header("Authorization", "Bearer <token>")
  .header("X-Namespace", "<api-key>")
  .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/buckets/{bucket_identifier}/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["X-Namespace"] = '<api-key>'
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",
      "queue_context": {},
      "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,
      "unaccounted_object_count": 38,
      "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
              },
              "segments_dropped": 5,
              "segments_dropped_reasons": {
                "config_cap_max_video_segments": 5
              },
              "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,
      "segments_dropped": null,
      "segments_dropped_reasons": null,
      "status_diagnostics": {},
      "documents_resolvable": false,
      "documents_resolvable_error": "<string>",
      "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>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

POST

buckets

{bucket_identifier}

batches

list

List Batches

curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/batches/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "offset": 0,
  "limit": 100
}
'

import requests

url = "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/batches/list"

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

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

print(response.text)

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

fetch('https://api.mixpeek.com/v1/buckets/{bucket_identifier}/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/buckets/{bucket_identifier}/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",
    "X-Namespace: <api-key>"
  ],
]);

$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/buckets/{bucket_identifier}/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("X-Namespace", "<api-key>")
	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/buckets/{bucket_identifier}/batches/list")
  .header("Authorization", "Bearer <token>")
  .header("X-Namespace", "<api-key>")
  .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/buckets/{bucket_identifier}/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["X-Namespace"] = '<api-key>'
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",
      "queue_context": {},
      "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,
      "unaccounted_object_count": 38,
      "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
              },
              "segments_dropped": 5,
              "segments_dropped_reasons": {
                "config_cap_max_video_segments": 5
              },
              "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,
      "segments_dropped": null,
      "segments_dropped_reasons": null,
      "status_diagnostics": {},
      "documents_resolvable": false,
      "documents_resolvable_error": "<string>",
      "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>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

Authorizations

Authorization

string

header

required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.

X-Namespace

string

header

required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

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,

INTERRUPTED,

UNKNOWN,

SKIPPED,

DRAFT,

ACTIVE,

ARCHIVED,

SUSPENDED,

DEACTIVATED

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.

namespace_id

string | null

Filter batches to a single namespace. Required here because POST /v1/batches/list is organization-scoped and does NOT read the X-Namespace header — that header is ignored on this endpoint, so pass the namespace here to narrow 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.

Show child attributes

total_count

integer

required

The total number of batches found.

pagination

Pagination · object | null

Pagination metadata including next_cursor for deep pagination.

Organization

Namespaces

Buckets

Feature Extractors

Batch Queue

Collections

Documents

Retrievers

Taxonomies

Clusters

Triggers

Alerts

Webhooks

Apps

Agent Sessions

Annotations

Templates

Manifest

Discovery

Analytics

Notifications

Tasks

Inference

Resource Search

Pricing

Events

Onboarding

List Batches

Authorizations

Path Parameters

Body

Response