Convert Batch

Convert more than one document in a single request. Sources can be web URLs (HTTP/HTTPS) or cloud storage (S3), and results are delivered either as temporary download URLs or written to a cloud storage destination you specify.

Use this endpoint whenever you have more than one document. For a single document, use Convert Source or Convert File.

Endpoint

POST /v1/convert/source/batch

Request Headers

Request Body

Sources

Each entry in sources is one of the following kinds. A single cloud storage source can represent many documents.

HTTP source

S3 source

Reads objects from an S3-compatible bucket. Every object under bucket/key_prefix is converted, up to max_num_elements.

Azure Blob Storage source

Reads blobs from an Azure Blob Storage container. Every blob under container/blob_prefix is converted, up to max_num_elements.

FileNet source

Reads documents from an IBM FileNet Content Manager / Cortex repository. You can specify either a folder to process all documents within it, or specific document IDs.

* Either folder_id or document_ids must be provided, but not both. If folder_id is specified, all documents in that folder are processed. If document_ids is specified, only those specific documents are processed.

Google Cloud Storage source

Reads objects from a Google Cloud Storage bucket. Every object under bucket/key_prefix is converted, up to max_num_elements.

When providing service_account_key, include these fields (from your GCP service account JSON key file):

SharePoint source

Reads documents from a SharePoint site or OneDrive for Business using Microsoft Graph API with app-only authentication.

* Exactly one of site_url or onedrive_user must be provided.

Google Drive source

Reads documents from Google Drive using OAuth 2.0 authentication. You can specify either a file or folder ID to process documents.

* One of token_path or refresh_token is required.

** One of credentials_path or credentials is required.

When providing the credentials object, include these fields (from your Google Cloud OAuth 2.0 Client ID):

Reads documents from a SharePoint site or OneDrive for Business using Microsoft Graph API with app-only authentication.

* Exactly one of site_url or onedrive_user must be provided.

Targets

The target determines where converted results are delivered. The choice is constrained by your sources:

Presigned URL target

The result contains one entry per document, each with a download URL for every requested output format.

S3 target

Writes the converted outputs to an S3-compatible bucket you specify. This can be any bucket; it does not have to be a source bucket, and source objects are never modified.

Azure Blob Storage target

Writes the converted outputs to an Azure Blob Storage container you specify. This can be any container; it does not have to be a source container, and source blobs are never modified.

Google Cloud Storage target

Writes the converted outputs to a Google Cloud Storage bucket you specify. This can be any bucket; it does not have to be a source bucket, and source objects are never modified.

When providing service_account_key, include the same fields as documented in the Google Cloud Storage source section.

SharePoint target

Writes the converted outputs to a SharePoint site or OneDrive for Business using Microsoft Graph API with app-only authentication. This can be any site or OneDrive; it does not have to be a source location.

* Exactly one of site_url or onedrive_user must be provided.

Google Drive target

Writes the converted outputs to Google Drive using OAuth 2.0 authentication. You can specify either a file or folder ID as the destination.

* One of token_path or refresh_token is required.

** One of credentials_path or credentials is required.

When providing the credentials object, include these fields (from your Google Cloud OAuth 2.0 Client ID):

AstraDB Chunks target

Writes document chunks with server-side embeddings to an AstraDB vector database collection. This target automatically chunks documents and generates embeddings using AstraDB's vectorize feature.

Options

The options object supports the following parameters:

Response

Success Response (200 OK)

Returns a task object that can be used to poll for completion:

{
  "task_id": "{TASK_ID}",
  "task_type": "convert",
  "task_status": "pending",
  "task_position": 1,
  "task_meta": null,
  "failure": null,
  "error_message": null
}

See Convert Source for the task field descriptions.

Retrieving Results

Poll /v1/status/poll/{task_id} until the status is success, then call /v1/result/{task_id}. The result shape depends on the target:

• presigned_url target — one entry per document with download URLs, plus result counters. See Get Results.
• s3 target — converted files are written to your destination bucket; the result is a summary of counts:

{
  "num_converted": 312,
  "num_succeeded": 310,
  "num_partially_succeeded": 1,
  "num_failed": 1,
  "processing_time": 842.5
}

Progress Callbacks

For long-running batches, you can have the service notify your own endpoint instead of polling. Each entry in callbacks describes a webhook:

Each callback request has the shape:

{
  "task_id": "{TASK_ID}",
  "progress": {
    "kind": "update_processed",
    "num_processed": 120,
    "num_succeeded": 118,
    "num_partially_succeeded": 1,
    "num_failed": 1,
    "docs": [
      { "source": "incoming/report.pdf", "status": "success", "error": null }
    ]
  }
}

The progress object's kind is one of:

Error Responses

See Error Handling for the full error model.

Examples

Find examples of using the batch endpoint in Converting Multiple Documents and Batch Conversion.

Related Endpoints

• Convert Source - Convert a single document from a URL
• Convert File - Upload and convert a single local file
• Poll Status - Check conversion progress
• Get Results - Retrieve conversion result artifacts