Beta

Batch Processing

Create Batch Job

Create a batch processing job.

Processes files from a directory or a specific list of item IDs. Supports batch parsing and classification operations.

Provide either directory_id to process all files in a directory, or item_ids for specific items. The job runs asynchronously — poll GET /batch/{job_id} for progress.

post/api/v1/beta/batch-processing

Query parameters

project_idstring uuid nullable

organization_idstring uuid nullable

Headers

temporal-namespacestring nullable

Cookies

sessionstring nullable

Request body

directory_idstring nullable

ID of the directory containing files to process

item_idsstring[] nullable

List of specific item IDs to process. Either this or directory_id must be provided.

page_sizeinteger

Number of files to process per batch when using directory mode

continue_as_new_thresholdinteger nullable

Maximum files to process per execution cycle in directory mode. Defaults to page_size.

Example request

{
  "directory_id": "dir-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "item_ids": [
    "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "dfl-11111111-2222-3333-4444-555555555555"
  ],
  "job_config": {
    "parameters": {
      "webhook_configurations": [
        {
          "webhook_url": "https://example.com/webhooks/llamacloud",
          "webhook_headers": {
            "Authorization": "Bearer sk-..."
          },
          "webhook_events": [
            "parse.success",
            "parse.error"
          ],
          "webhook_output_format": "json"
        }
      ]
    }
  }
}

Response

Successful Response

Status of a batch processing job.

effective_atstring date-time

job_record_idstring nullable

The job record ID associated with this status, if any.

error_messagestring nullable

Error message for the latest job attempt, if any.

idstring required

Unique identifier for the batch job

created_atstring date-time nullable

Creation datetime

updated_atstring date-time nullable

Update datetime

project_idstring required

Project this job belongs to

directory_idstring nullable

Directory being processed

job_type'parse' | 'extract' | 'classify' required

Type of batch processing operation.

total_itemsinteger required

Total number of items in the job

processed_itemsinteger

Number of items processed so far

failed_itemsinteger

Number of items that failed processing

skipped_itemsinteger

Number of items skipped (already processed or size limit)

workflow_idstring nullable

Async job tracking ID

started_atstring date-time nullable

Timestamp when job processing started

completed_atstring date-time nullable

Timestamp when job completed

Example response

{
  "id": "bjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "project_id": "proj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "directory_id": "dir-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}

Changes

Changed in 2 of the 33 revisions of this API.8

Jun 9, 2026b17341164de92See the full diff
- ○
  added the optional property detail/items/ctx to the response with the 422 status
  response-optional-property-added
- ○
  added the optional property detail/items/input to the response with the 422 status
  response-optional-property-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jun 4, 2026d40e17e17bd16See the full diff
- ○
  added the new classify.running enum value to the request property job_config/anyOf[subschema #1: BatchParseJobRecordCreate]/parameters/anyOf[subschema #1: BatchParseJobConfig]/webhook_configurations/anyOf[subschema #1]/items/webhook_events/anyOf[subschema #1]/items/
  request-property-enum-value-added
- ○
  added the new sheets.cancelled enum value to the request property job_config/anyOf[subschema #1: BatchParseJobRecordCreate]/parameters/anyOf[subschema #1: BatchParseJobConfig]/webhook_configurations/anyOf[subschema #1]/items/webhook_events/anyOf[subschema #1]/items/
  request-property-enum-value-added
- ○
  added the new sheets.error enum value to the request property job_config/anyOf[subschema #1: BatchParseJobRecordCreate]/parameters/anyOf[subschema #1: BatchParseJobConfig]/webhook_configurations/anyOf[subschema #1]/items/webhook_events/anyOf[subschema #1]/items/
  request-property-enum-value-added
- ○
  added the new sheets.partial_success enum value to the request property job_config/anyOf[subschema #1: BatchParseJobRecordCreate]/parameters/anyOf[subschema #1: BatchParseJobConfig]/webhook_configurations/anyOf[subschema #1]/items/webhook_events/anyOf[subschema #1]/items/
  request-property-enum-value-added
- ○
  added the new sheets.pending enum value to the request property job_config/anyOf[subschema #1: BatchParseJobRecordCreate]/parameters/anyOf[subschema #1: BatchParseJobConfig]/webhook_configurations/anyOf[subschema #1]/items/webhook_events/anyOf[subschema #1]/items/
  request-property-enum-value-added
- ○
  added the new sheets.success enum value to the request property job_config/anyOf[subschema #1: BatchParseJobRecordCreate]/parameters/anyOf[subschema #1: BatchParseJobConfig]/webhook_configurations/anyOf[subschema #1]/items/webhook_events/anyOf[subschema #1]/items/
  request-property-enum-value-added

Full history