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 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "offset": 0,
  "limit": 100
}'
{
  "batches": [
    {
      "batch_id": "btch_simple_001",
      "bucket_id": "bkt_videos",
      "collection_ids": [
        "col_chunks"
      ],
      "dag_tiers": [
        [
          "col_chunks"
        ]
      ],
      "description": "Simple single-tier batch (DRAFT)",
      "metadata": {
        "campaign_id": "Q4_2025"
      },
      "object_ids": [
        "obj_video_001",
        "obj_video_002"
      ],
      "status": "DRAFT",
      "tier_tasks": [],
      "total_tiers": 1,
      "type": "BUCKET"
    }
  ],
  "total_count": 123
}

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"

​
X-Namespace
string
required

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. 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 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, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state.

Polling Guidance: - Poll tasks in PENDING, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling

Available options:
PENDING,
IN_PROGRESS,
PROCESSING,
COMPLETED,
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.

​
batches
BatchModel · object[]
required

A list of batches.

​
total_count
integer
required

The total number of batches found.