Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Bucket Batches

List Batches

List batches with pagination and filtering options.

post/v1/buckets/{bucket_identifier}/batches/list

Path parameters

bucket_identifierstring required

The unique identifier of the bucket.

The unique identifier of the bucket.

Request body

status'PENDING' | 'QUEUED' | 'IN_PROGRESS' | 'PROCESSING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELED' | 'INTERRUPTED' | 'UNKNOWN' | 'SKIPPED' | 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'SUSPENDED'

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 COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success) 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, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state.

Partial Success Handling: COMPLETED_WITH_ERRORS indicates that the operation completed but some documents/items failed. The task result includes: - List of successful items - List of failed items with error details - Success rate percentage This allows clients to handle partial success scenarios appropriately.

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

collection_idstring nullable

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_idstring nullable

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

offsetinteger

The number of batches to skip.

limitinteger

The maximum number of batches to return.

cursorstring nullable

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

total_countinteger required

The total number of batches found.

paginationobject nullable

Pagination metadata including next_cursor for deep pagination.

Example response

{
  "results": [
    {
      "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"
    }
  ]
}