Batch Split Files

from extend_ai import Extend, FileFromUrl
from extend_ai.split_runs import SplitRunsCreateBatchRequestSplitter, SplitRunsCreateBatchRequestInputsItem
client = Extend(
    token="YOUR_TOKEN_HERE",
    extend_api_version="2026-02-09",
)
client.split_runs.create_batch(
    splitter=SplitRunsCreateBatchRequestSplitter(
        id="spl_xK9mLPqRtN3vS8wF5hB2cQ",
    ),
    inputs=[
        SplitRunsCreateBatchRequestInputsItem(
            file=FileFromUrl(
                url="https://example.com/multi-doc1.pdf",
            ),
            metadata={
                "customerId": "cust_abc123"
            },
        ),
        SplitRunsCreateBatchRequestInputsItem(
            file=FileFromUrl(
                url="https://example.com/multi-doc2.pdf",
            ),
            metadata={
                "customerId": "cust_def456"
            },
        ),
        SplitRunsCreateBatchRequestInputsItem(
            file=FileFromUrl(
                url="https://example.com/multi-doc3.pdf",
            ),
            metadata={
                "customerId": "cust_ghi789"
            },
        )
    ],
)

{
  "object": "batch_run",
  "id": "bpr_Xj8mK2pL9nR4vT7qY5wZ",
  "status": "PROCESSING",
  "runCount": 50,
  "createdAt": "2024-03-21T16:45:00Z"
}

Submit up to 1,000 files for splitting in a single request. Each file is processed as an independent split run using the same splitter and configuration.

Unlike the single Split File (Async) endpoint, this batch endpoint accepts an inputs array and immediately returns a BatchRun object containing a batch id and a PENDING status. The individual runs are then queued and processed asynchronously.

Monitoring results:

Webhooks (recommended): Subscribe to batch_processor_run.processed and batch_processor_run.failed events. The webhook payload indicates the batch has finished — fetch individual run results using GET /split_runs?batchId={id}.
Polling: Call GET /batch_runs/{id} to check the overall batch status, and use GET /split_runs filtered by batchId to retrieve individual run results.

Notes:

A processor reference (splitter.id) is required — inline config is not supported for batch requests.
inputs must contain between 1 and 1,000 items.
All inputs in a batch use the same splitter version and override config.
Raw text input (FileFromText) is not supported for split runs. Use a URL or file ID.

Submit up to **1,000 files** for splitting in a single request. Each file is processed as an independent split run using the same splitter and configuration. Unlike the single [Split File (Async)](https://docs.extend.ai/2026-02-09/api-reference/endpoints/split/create-split-run) endpoint, this batch endpoint accepts an `inputs` array and immediately returns a `BatchRun` object containing a batch `id` and a `PENDING` status. The individual runs are then queued and processed asynchronously. **Monitoring results:** - **Webhooks (recommended):** Subscribe to `batch_processor_run.processed` and `batch_processor_run.failed` events. The webhook payload indicates the batch has finished — fetch individual run results using `GET /split_runs?batchId={id}`. - **Polling:** Call `GET /batch_runs/{id}` to check the overall batch status, and use `GET /split_runs` filtered by `batchId` to retrieve individual run results. **Notes:** - A processor reference (`splitter.id`) is required — inline `config` is not supported for batch requests. - `inputs` must contain between 1 and 1,000 items. - All inputs in a batch use the same splitter version and override config. - Raw text input (`FileFromText`) is not supported for split runs. Use a URL or file ID.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

splitterobjectRequired

Reference to the splitter to run against every input in this batch.

inputslist of objectsRequired

An array of inputs to process. Each item produces one split run. Must contain between 1 and 1,000 items. Raw text input is not supported — use a URL or file ID.

priorityintegerOptional1-100Defaults to 50

An optional value used to determine the relative order of runs when rate limiting is in effect. Lower values will be prioritized before higher values.

Response

Successfully queued batch split run

objectenum

The type of object. Always "batch_run".

Allowed values:

idstring

The unique identifier for this batch run.

Example: "bpr_Xj8mK2pL9nR4vT7qY5wZ"

statusenum

The status of a batch run:

"PENDING" - The batch has been created and is waiting to be processed
"PROCESSING" - The batch is currently being processed
"PROCESSED" - All runs in the batch have completed successfully
"FAILED" - The batch failed to process
"CANCELLED" - The batch was cancelled

Allowed values:

runCountinteger

The number of individual runs in this batch.

createdAtstringformat: "date-time"

The time (in UTC) at which the object was created. Will follow the RFC 3339 format.

Example: "2024-03-21T16:45:00Z"

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

Submit up to 1,000 files for splitting in a single request. Each file is processed as an independent split run using the same splitter and configuration.

Monitoring results:

Webhooks (recommended): Subscribe to batch_processor_run.processed and batch_processor_run.failed events. The webhook payload indicates the batch has finished — fetch individual run results using GET /split_runs?batchId={id}.
Polling: Call GET /batch_runs/{id} to check the overall batch status, and use GET /split_runs filtered by batchId to retrieve individual run results.

Notes:

A processor reference (splitter.id) is required — inline config is not supported for batch requests.
inputs must contain between 1 and 1,000 items.
All inputs in a batch use the same splitter version and override config.
Raw text input (FileFromText) is not supported for split runs. Use a URL or file ID.

Batch Split Files

Authentication

Headers

Request

Response

Errors

Authentication

Headers

Request

Response

Errors