Sign in

v

OpenAPI 3.1.02026-08-085671,1112.8 MB
Batches

List All Batches

List batches across all buckets in the organization. Filter with status, bucket_id, collection_id, or namespace_id in the request body. NOTE: the X-Namespace header does NOT narrow this endpoint — it is organization-scoped by design. Pass namespace_id in the body instead.

post/v1/batches/list

Request body

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

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.

namespace_idstring nullable

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.

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"
    }
  ]
}