Skip to content
Guide
Split

Split response format

Field-by-field reference for the Split job response — the job envelope and statuses, result segments with category, 1-indexed page numbers and confidence level, uncategorized-page handling, the beta endpoint differences, and how to feed segments into Parse, Extract, or Classify.

A Split job returns one object, the split job, from POST /api/v1/split/jobs, GET /api/v1/split/jobs/{split_job_id}, and the cancel endpoint. The SDKs return the same object from client.split.create() and client.split.get(). This page lists every field in that object and what each one means. For defining categories and running jobs, see Getting started; for the request side, see the Split API reference.

Split is currently in beta and is subject to breaking changes.

Field Type Description
id string Job identifier, prefixed spl-. Pass it to GET /api/v1/split/jobs/{split_job_id}.
status string Job state. See Job status.
file_input string The file ID or parse job ID the job ran on.
document_input_type string What file_input refers to: file_id, parse_job_id, or url.
categories array The categories the job split against, each with name and an optional description. Echoed from the request or the saved configuration.
splitting_strategy object The strategy the job ran with: allow_uncategorized, custom_instructions, and min_pages_per_split. See Uncategorized pages and merging.
parse_tier string or null Parse tier requested for the job. null means the default, fast. Not used when file_input is a completed Parse job.
parse_config_id string or null Saved parse configuration ID requested for the job, if any. Takes precedence over parse_tier.
target_pages string or null Page selection requested for the job (1-based, "1-3,7"), if any. Accepted only when file_input is a completed Parse job.
configuration_id string or null Saved configuration ID used for the job, if any.
version string Split version the job ran with, such as 1.1.0. A job created without a version reports the release it resolved to.
result object or null The segments. Present only when status is completed. See result.segments.
error_message string or null Why the job failed, when status is failed.
transaction_id string or null The idempotency key supplied at creation, if any. Reusing a key returns the original job.
project_id string Project the job belongs to.
user_id string User who created the job.
created_at, updated_at datetime Creation and last-update timestamps.

Split statuses are lowercase, unlike the uppercase statuses of Extract and Classify jobs.

status Meaning
pending Queued, not yet started.
processing Actively processing.
completed Finished; result is populated.
failed Terminated with an error; result is null, read error_message.
cancelled Cancelled by the user; result is null.

Poll GET /api/v1/split/jobs/{split_job_id} until the status is one of the three terminal values.

result has a single field, segments, an array with one element per detected document section. Each segment has:

Field Type Description
category string The name of the category the segment was assigned to, or uncategorized when no category matched and allow_uncategorized is include.
pages array of integers The 1-indexed page numbers that make up the segment.
confidence_category string Confidence in the assignment: high, medium, or low.

Page numbers are those of the input document, so with target_pages set they still refer to the original pages. Split detects where one document ends and the next begins, so adjacent segments can share a category: a bundle of three invoices in a row comes back as three invoice segments, not one.

From Getting started, on the sample shipping bundle:

{
"id": "spl-abc123...",
"status": "completed",
"result": {
"segments": [
{ "category": "invoice", "pages": [1], "confidence_category": "high" },
{ "category": "uncategorized", "pages": [2], "confidence_category": "high" },
{ "category": "invoice", "pages": [3], "confidence_category": "high" },
{ "category": "uncategorized", "pages": [4], "confidence_category": "high" },
{ "category": "uncategorized", "pages": [5], "confidence_category": "high" },
{ "category": "uncategorized", "pages": [6], "confidence_category": "high" },
{ "category": "uncategorized", "pages": [7], "confidence_category": "high" },
{ "category": "uncategorized", "pages": [8], "confidence_category": "high" },
{ "category": "certificate", "pages": [9], "confidence_category": "high" },
{ "category": "uncategorized", "pages": [10], "confidence_category": "high" },
{ "category": "certificate", "pages": [11], "confidence_category": "high" },
{ "category": "certificate", "pages": [12], "confidence_category": "high" },
{ "category": "certificate", "pages": [13], "confidence_category": "high" },
{ "category": "certificate", "pages": [14], "confidence_category": "high" },
{ "category": "certificate", "pages": [15], "confidence_category": "high" }
]
}
}

Three splitting_strategy options change which pages appear in result.segments:

Option Values Effect on the result
allow_uncategorized include (default) Pages that match no category are grouped into segments with category set to uncategorized. Every page of the document appears in some segment.
forbid Every page must be assigned to one of your categories; no uncategorized segment is returned.
omit Pages that match no category are left out of result.segments, so the union of pages across segments can be smaller than the document.
min_pages_per_split integer, default 1 Segments shorter than this are merged into an adjacent segment. 1 disables merging.
custom_instructions string or null Free-form guidance that steers where boundaries fall; it combines with the category descriptions rather than replacing them.

The values the job actually ran with are echoed back in the response’s splitting_strategy, so a reader of the result can tell whether missing pages were omitted on purpose.

The beta endpoints, POST /api/v1/beta/split/jobs and GET /api/v1/beta/split/jobs/{split_job_id} (client.beta.split in the SDKs), return the same id, status, categories, configuration_id, result, error_message, project_id, user_id, created_at, and updated_at. They differ in how the input is reported:

Beta response Replaces
document_input — an object with type (file_id) and value (the file ID) file_input and document_input_type
no splitting_strategy, transaction_id, parse_tier, parse_config_id, target_pages, or version fields the echoed strategy, idempotency key, parse settings, and Split version

result.segments is identical on both endpoints.

On both endpoints a request carries either configuration_id or an inline configuration, not both. GET /api/v1/split/jobs lists jobs with the same items, next_page_token and optional total_size shape as the other products, filterable by status and job_ids; in the SDKs, client.split.list() returns a cursor you can iterate directly.

A segment’s pages array is the handle for the next step. The file ID in file_input can be reused, so the usual pattern is one downstream job per segment, scoped to that segment’s pages with a 1-based target_pages string built from the segment, such as "4-8":

  • Extract: set target_pages in the Extract configuration and pick the data_schema by category. The resume book example builds the string as f"{min(segment.pages)}-{max(segment.pages)}".
  • Parse: set page_ranges.target_pages in the Parse configuration; see Page ranges.
  • Classify: set parsing_configuration.target_pages on the classify job when a segment needs a finer label than its Split category.

Because pages is a list, not a range, build the string from its values rather than assuming the pages are contiguous.

Download a sample bundle of shipping documents that includes invoices and export certificates:

Terminal window
curl -fL -o bundle.pdf https://cloud.llamaindex.ai/assets/demos/split/shipping.pdf
import os
import time
from llama_cloud import LlamaCloud
client = LlamaCloud(api_key=os.environ["LLAMA_CLOUD_API_KEY"])
file_obj = client.files.create(file="bundle.pdf", purpose="split")
job = client.split.create(
file_input=file_obj.id,
configuration={
"categories": [
{"name": "invoice", "description": "A commercial document requesting payment for goods or services"},
{"name": "certificate", "description": "A certificate of origin, health certificate, or other export certificate issued by a government agency or chamber of commerce"},
],
"splitting_strategy": {"allow_uncategorized": "include"},
},
)
# Poll until the job reaches a terminal state
job = client.split.get(job.id)
while job.status not in ("completed", "failed", "cancelled"):
time.sleep(2)
job = client.split.get(job.id)
print(job.status, job.splitting_strategy)
if job.result is None:
print(f"No result: {job.error_message}")
else:
for segment in job.result.segments:
pages = f"{min(segment.pages)}-{max(segment.pages)}"
print(segment.category, pages, segment.confidence_category)
Note for AI agents: this documentation is built for programmatic access. - Overview of all docs: https://developers.llamaindex.ai/llms.txt - Any page is available as raw Markdown by appending index.md to its URL — e.g. https://developers.llamaindex.ai/llamaparse/parse/getting_started/index.md - Agent-friendly REST search APIs live under https://developers.llamaindex.ai/api/ — search (BM25 full-text), grep (regex), read (fetch a page), and list (browse the doc tree). See https://developers.llamaindex.ai/llms.txt for parameters. - A hosted documentation MCP server is available at https://developers.llamaindex.ai/mcp. If you support MCP, you can ask the user to install it for browsing these docs directly (an alternative to the REST API). Setup: https://developers.llamaindex.ai/for-agents/mcp/ - Other LlamaIndex tooling for agents — the LlamaParse Platform MCP server, agent skills and plugins, and the n8n node — is mapped at https://developers.llamaindex.ai/for-agents/