Account1

Adhoc Retrievers3

Agent Sessions11

Alerts16

Analytics42

Annotations9

Apps34

Batches4

Bucket Batches23

Bucket Objects10

Bucket Syncs15

Bucket Uploads7

Buckets7

BYO Documents5

Cluster Executions7

Cluster Triggers8

Clusters10

Collection Documents19

Collection Lifecycle2

Collection Schema1

Collection Taxonomies1

Collections14

Custom Models8

Data Subject Access Requests3

Discovery4

Document Lineage3

Documents6

Events1

Extractor Publishing5

Extractors5

Feature Extractors2

Feature Search1

Features1

Health4

Inference1

Manifest7

Marketplace14

Models6

Namespace Clone1

Namespace Extractors2

Namespace Migrations7

Namespace Snapshots6

Namespaces10

Notifications13

Onboarding2

Ops1

Organization API Keys5

Organization Audit5

Organization Billing22

Organization Connections8

Organization Infrastructure1

Organization Secrets4

Organization Targets1

Organization Usage3

Organization Users5

Organizations4

Pricing1

Public Apps API5

Public Extractor Marketplace2

Public Notifications API1

Public Retriever API7

Public Templates API8

Published Retrievers8

Quickstart1

Resource Search1

Retriever API Keys3

Retriever Benchmarks4

Retriever Evaluations9

Retriever Interactions5

Retriever Learned Fusion10

Retriever Stages1

Retrievers15

Scaffold Templates3

Source Adapter2

Support14

Tasks3

Taxonomies13

Taxonomy Analytics6

Templates24

Triggers10

Webhooks5

Batches

List All Batches

List batches across the organization. The X-Namespace header narrows the list to that namespace, exactly like every other namespaced endpoint; omit it for the org-wide view. namespace_id in the request body also works (and wins ties when it agrees with the header; a conflicting header + body is a 400). Other body filters: status, bucket_id, collection_id.

post/v1/batches/list

Request body

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

Changes

Changed in 9 of the 33 revisions of this API.415

Sep 2, 20268ef32f2ad1a61See the full diff
- ●
  added the new mvs_durability enum value to the /// response property for the response status
  response-property-enum-value-added
Aug 30, 20263775e0b36ee11See the full diff
- ○
  added the optional property ////// to the response with the status
  response-optional-property-added
Aug 16, 20266e8256aacbc52See the full diff
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
Aug 9, 20265d4c905106b41See the full diff
- ○
  the endpoint scheme security BearerAuth was added to the API
  api-security-added
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 8, 2026220a3b263fda1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Aug 4, 20269603dfdab46332See the full diff
- ●
  added the new DEACTIVATED enum value to the // response property for the response status
  response-property-enum-value-added
- ●
  added the new DEACTIVATED enum value to the ////// response property for the response status
  response-property-enum-value-added
- ●
  added the new DEACTIVATED enum value to the //// response property for the response status
  response-property-enum-value-added
- ○
  added the new DEACTIVATED enum value to the request property /
  request-property-enum-value-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
Aug 1, 20266c69078922c25See the full diff
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property ////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////// to the response with the status
  response-optional-property-added
Jul 31, 2026a99bd9ec84c72See the full diff
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
Jul 26, 20267cb0515333111See the full diff
- ○
  added the optional property // to the response with the status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history