## Create Split Job

`client.split.create(SplitCreateParamsparams, RequestOptionsoptions?): SplitCreateResponse`

**post** `/api/v1/split/jobs`

Create a split job.

## Document input

Set `file_input` to a file ID or a completed parse job ID (`pjb-...`). Supplying a parse job reuses its output instead of reading the document again.

## Page selection

`configuration.target_pages` selects which pages of a supplied parse job to split (1-based; `1-50`, `1,3,5-7`). Pages are read in ascending document order, and each segment's `pages` are the parse job's own page numbers, so segments map straight back to the original document. Requires a parse job as `file_input`; passing it with a file ID returns 400.

## Parse settings

`configuration.parse_tier` and `configuration.parse_config_id` control how the document is read before splitting; both are ignored when a parse job is supplied. A parse configuration restricted to a page subset (`target_pages` or `max_pages`) is rejected, since split results always number pages relative to the full document.

The job runs asynchronously. Poll `GET /split/jobs/{split_job_id}` or register a webhook to monitor completion.

### Parameters

- `params: SplitCreateParams`

  - `file_input: string`

    Body param: File ID or parse job ID

  - `organization_id?: string | null`

    Query param

  - `project_id?: string | null`

    Query param

  - `configuration?: Configuration | null`

    Body param: Split configuration with categories and splitting strategy.

    - `categories: Array<SplitCategory>`

      Categories to split documents into.

      - `name: string`

        Name of the category.

      - `description?: string | null`

        Optional description of what content belongs in this category.

    - `parse_config_id?: string | null`

      Saved parse configuration ID to control how the document is parsed before splitting. Takes precedence over parse_tier. Configurations that restrict pages (`target_pages` or `max_pages` on the parse configuration) are rejected: split results number pages relative to the full document. Ignored when a completed parse job is supplied as file_input.

    - `parse_tier?: "agentic" | "agentic_plus" | "cost_effective" | "fast" | null`

      Parse tier used to read the document before splitting. Defaults to fast. Ignored when a completed parse job is supplied as file_input.

      - `"agentic"`

      - `"agentic_plus"`

      - `"cost_effective"`

      - `"fast"`

    - `splitting_strategy?: SplittingStrategy`

      Strategy for splitting documents.

      - `allow_uncategorized?: "forbid" | "include" | "omit"`

        Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results.

        - `"forbid"`

        - `"include"`

        - `"omit"`

      - `custom_instructions?: string | null`

        Free-form guidance for where segment boundaries are placed.

      - `min_pages_per_split?: number`

        Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging.

    - `target_pages?: string | null`

      Comma-separated page numbers or ranges to split (1-based). Pages are split in the order listed. Omit to split all pages. Requires a completed parse job as file_input.

    - `version?: string | null`

      Split version to run. Omit for the current release. Preview versions are selectable by name and never resolved automatically.

  - `configuration_id?: string | null`

    Body param: Saved configuration ID

  - `transaction_id?: string | null`

    Body param: Idempotency key scoped to the project. Reusing a key returns the original job; the new request body is ignored.

  - `webhook_configuration_ids?: Array<string> | null`

    Body param: IDs of saved webhook configurations to notify for this job.

  - `webhook_configurations?: Array<WebhookConfiguration> | null`

    Body param: Outbound webhook endpoints to notify on job status changes

    - `webhook_events?: Array<"batch.cancelled" | "batch.error" | "batch.pending" | 35 more> | null`

      Events to subscribe to (e.g. 'parse.success', 'extract.error'). If null, all events are delivered.

      - `"batch.cancelled"`

      - `"batch.error"`

      - `"batch.pending"`

      - `"batch.running"`

      - `"batch.success"`

      - `"classify.cancelled"`

      - `"classify.error"`

      - `"classify.partial_success"`

      - `"classify.pending"`

      - `"classify.running"`

      - `"classify.success"`

      - `"extract.cancelled"`

      - `"extract.error"`

      - `"extract.partial_success"`

      - `"extract.pending"`

      - `"extract.success"`

      - `"parse.cancelled"`

      - `"parse.error"`

      - `"parse.partial_success"`

      - `"parse.pending"`

      - `"parse.running"`

      - `"parse.success"`

      - `"sheets.cancelled"`

      - `"sheets.error"`

      - `"sheets.partial_success"`

      - `"sheets.pending"`

      - `"sheets.success"`

      - `"split.cancelled"`

      - `"split.error"`

      - `"split.pending"`

      - `"split.processing"`

      - `"split.success"`

      - `"unmapped_event"`

      - `"verify.cancelled"`

      - `"verify.error"`

      - `"verify.pending"`

      - `"verify.running"`

      - `"verify.success"`

    - `webhook_headers?: Record<string, string> | null`

      Custom HTTP headers sent with each webhook request (e.g. auth tokens)

    - `webhook_output_format?: string | null`

      Response format sent to the webhook: 'string' (default) or 'json'

    - `webhook_signing_secret?: string | null`

      Shared signing secret used to sign webhook deliveries. When set, each request includes an HMAC-SHA256 signature of the request body in the 'LC-Signature' header (value 'sha256=<hex>'). Recompute the HMAC over the raw request body with this secret to verify the delivery is authentic.

    - `webhook_url?: string | null`

      URL to receive webhook POST notifications

### Returns

- `SplitCreateResponse`

  A split job.

  - `id: string`

    Unique identifier for the split job.

  - `categories: Array<SplitCategory>`

    Categories used for splitting.

    - `name: string`

      Name of the category.

    - `description?: string | null`

      Optional description of what content belongs in this category.

  - `document_input_type: "file_id" | "parse_job_id" | "url"`

    Whether the input was a file or parse job

    - `"file_id"`

    - `"parse_job_id"`

    - `"url"`

  - `file_input: string`

    File ID or parse job ID

  - `project_id: string`

    Project this job belongs to.

  - `status: string`

    Current job status. Valid values are: pending, processing, completed, failed, cancelled.

  - `user_id: string`

    User who created this job.

  - `configuration_id?: string | null`

    Split configuration ID used for this job.

  - `created_at?: string | null`

    Creation datetime

  - `error_message?: string | null`

    Error message if the job failed.

  - `parse_config_id?: string | null`

    Saved parse configuration ID requested for this job, if any.

  - `parse_tier?: string | null`

    Parse tier requested for this job, if any.

  - `result?: SplitResultResponse | null`

    Result of a completed split job.

    - `segments: Array<SplitSegmentResponse>`

      List of document segments.

      - `category: string`

        Category name this split belongs to.

      - `confidence_category: string`

        Categorical confidence level. Valid values are: high, medium, low.

      - `pages: Array<number>`

        Page numbers in this segment, as numbered by the input document.

  - `splitting_strategy?: SplittingStrategy`

    Strategy used for splitting.

    - `allow_uncategorized?: "forbid" | "include" | "omit"`

      Controls handling of pages that don't match any category. 'include': pages can be grouped as 'uncategorized' and included in results. 'forbid': all pages must be assigned to a defined category. 'omit': pages can be classified as 'uncategorized' but are excluded from results.

      - `"forbid"`

      - `"include"`

      - `"omit"`

    - `custom_instructions?: string | null`

      Free-form guidance for where segment boundaries are placed.

    - `min_pages_per_split?: number`

      Minimum pages per segment. Shorter segments are merged into an adjacent segment; 1 disables merging.

  - `target_pages?: string | null`

    Page selection requested for this job, if any.

  - `transaction_id?: string | null`

    Idempotency key scoped to the project, if one was provided.

  - `updated_at?: string | null`

    Update datetime

### Example

```typescript
import LlamaCloud from '@llamaindex/llama-cloud';

const client = new LlamaCloud({
  apiKey: process.env['LLAMA_CLOUD_API_KEY'], // This is the default and can be omitted
});

const split = await client.split.create({ file_input: 'dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' });

console.log(split.id);
```

#### Response

```json
{
  "id": "id",
  "categories": [
    {
      "name": "x",
      "description": "x"
    }
  ],
  "document_input_type": "file_id",
  "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "project_id": "project_id",
  "status": "status",
  "user_id": "user_id",
  "configuration_id": "configuration_id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "error_message": "error_message",
  "parse_config_id": "parse_config_id",
  "parse_tier": "parse_tier",
  "result": {
    "segments": [
      {
        "category": "category",
        "confidence_category": "confidence_category",
        "pages": [
          0
        ]
      }
    ]
  },
  "splitting_strategy": {
    "allow_uncategorized": "forbid",
    "custom_instructions": "Start a new segment at every signature page.",
    "min_pages_per_split": 1
  },
  "target_pages": "target_pages",
  "transaction_id": "transaction_id",
  "updated_at": "2019-12-27T18:11:19.117Z"
}
```