LlamaParse Batches API
The Batches API from LlamaParse — 2 operation(s) for batches.
OpenAPI Specification
openapi: 3.0.3
info:
title: Llama Platform Agent Data Batches API
version: 0.1.0
tags:
- name: Batches
paths:
/api/v2/batches:
post:
tags:
- Batches
summary: Create Batch
description: Create a batch over a source directory and start processing asynchronously.
operationId: create_batch_api_v2_batches_post
security:
- HTTPBearer: []
parameters:
- name: project_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Project Id
- name: organization_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Organization Id
- name: session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCreateRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BatchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Batches
summary: List Batches
description: List batches for the current project.
operationId: list_batches_api_v2_batches_get
security:
- HTTPBearer: []
parameters:
- name: project_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Project Id
- name: organization_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Organization Id
- name: page_size
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Page Size
- name: page_token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Page Token
- name: created_at_on_or_after
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At On Or After
- name: created_at_on_or_before
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At On Or Before
- name: status
in: query
required: false
schema:
anyOf:
- enum:
- PENDING
- THROTTLED
- RUNNING
- COMPLETED
- FAILED
- CANCELLED
type: string
- type: 'null'
title: Status
- name: source_directory_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Source Directory Id
- name: session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BatchQueryResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/batches/{batch_id}:
get:
tags:
- Batches
summary: Get Batch
description: Get a batch by ID.
operationId: get_batch_api_v2_batches__batch_id__get
security:
- HTTPBearer: []
parameters:
- name: batch_id
in: path
required: true
schema:
type: string
title: Batch Id
- name: expand
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: 'Fields to expand. Supported value: results.'
title: Expand
description: 'Fields to expand. Supported value: results.'
- name: project_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Project Id
- name: organization_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Organization Id
- name: session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BatchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
BatchCreateRequest:
properties:
source_directory_id:
type: string
title: Source Directory Id
description: Directory whose files should be processed.
examples:
- dir-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
config:
$ref: '#/components/schemas/BatchConfiguration'
description: Batch configuration snapshot to apply to this source directory.
type: object
required:
- source_directory_id
- config
title: BatchCreateRequest
description: "Create a batch over a directory.\n\nExample:\n {\n \"source_directory_id\": \"dir-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n \"config\": {\n \"job\": {\n \"type\": \"parse_v2\",\n \"configuration_id\": \"cfg-PARSE_AGENTIC\"\n }\n },\n }\n\nThe source is always a directory. Callers upload or attach files to the\ndirectory first, then this API maps each source directory file to an\noutput job such as a parse job ID."
BatchJobReference:
properties:
type:
anyOf:
- type: string
const: parse_v2
- type: string
const: extract_v2
title: Type
description: Type of job produced for the file.
id:
type: string
title: Id
description: Job ID, such as a parse job ID.
examples:
- pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
type: object
required:
- type
- id
title: BatchJobReference
description: "Reference to a job produced by a batch.\n\nExample:\n {\n \"type\": \"parse_v2\",\n \"id\": \"pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"\n }"
BatchResponse:
properties:
id:
anyOf:
- type: string
- type: string
format: uuid
title: Id
description: Unique identifier
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: Creation datetime
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
description: Update datetime
project_id:
type: string
title: Project Id
description: Project this batch belongs to.
source_directory_id:
type: string
title: Source Directory Id
description: Directory being processed.
config:
$ref: '#/components/schemas/BatchConfiguration'
description: Batch configuration snapshot.
status:
type: string
enum:
- PENDING
- THROTTLED
- RUNNING
- COMPLETED
- FAILED
- CANCELLED
title: Status
description: Current batch status.
results:
anyOf:
- items:
$ref: '#/components/schemas/BatchResult'
type: array
- type: 'null'
title: Results
description: Expanded per-file result mappings. Null unless requested with expand=results, or while the batch is still running.
type: object
required:
- id
- project_id
- source_directory_id
- config
- status
title: BatchResponse
description: "A top-level batch.\n\nExample:\n {\n \"id\": \"bat-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n \"project_id\": \"prj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n \"source_directory_id\": \"dir-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n \"config\": {\n \"job\": {\n \"type\": \"parse_v2\",\n \"configuration_id\": \"cfg-PARSE_AGENTIC\"\n }\n },\n \"status\": \"COMPLETED\",\n \"results\": [\n {\n \"source_directory_file_id\": \"dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n \"job_reference\": {\n \"type\": \"parse_v2\",\n \"id\": \"pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"\n },\n \"error_message\": null\n }\n ]\n }\n\nBatch-level ``FAILED`` means the orchestration failed and cannot provide a\nreliable per-file result set. ``results`` is only populated when explicitly\nrequested with ``expand=results`` and may be ``null`` while a batch is still\nrunning."
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
BatchJobConfig:
properties:
type:
anyOf:
- type: string
const: parse_v2
- type: string
const: extract_v2
title: Type
description: Product job type to run for each source directory file.
examples:
- parse_v2
- extract_v2
configuration_id:
type: string
title: Configuration Id
description: Product configuration ID or built-in preset ID matching the job type.
examples:
- cfg-PARSE_AGENTIC
type: object
required:
- type
- configuration_id
title: BatchJobConfig
description: "Job to run for each file in the source directory.\n\nExample:\n {\n \"type\": \"parse_v2\",\n \"configuration_id\": \"cfg-PARSE_AGENTIC\"\n }\n\nBatch V2 references product configuration IDs so the underlying\ndirectory-sync flow can resolve a stable config ID for every file-level job.\nIDs may refer to saved project configurations or built-in presets for the\nrequested product type."
BatchResult:
properties:
source_directory_file_id:
type: string
title: Source Directory File Id
description: Source directory file processed by this batch.
examples:
- dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
job_reference:
anyOf:
- $ref: '#/components/schemas/BatchJobReference'
- type: 'null'
description: Job created for this file, once known.
error_message:
anyOf:
- type: string
- type: 'null'
title: Error Message
description: Batch-level mapping error if the system could not create or associate a job for this source file.
type: object
required:
- source_directory_file_id
title: BatchResult
description: "Result projection for one source directory file in a batch.\n\nExample:\n {\n \"source_directory_file_id\": \"dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n \"job_reference\": {\n \"type\": \"parse_v2\",\n \"id\": \"pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"\n },\n \"error_message\": null\n }\n\nThis is a projection of directory-sync state, not a separate child\nresource that callers need to create. The source directory file ID is the\nstable correlation key. Underlying job progress and failures should be\nresolved through the referenced product job endpoint."
BatchConfiguration:
properties:
job:
$ref: '#/components/schemas/BatchJobConfig'
description: Job to create for each file in the source directory.
type: object
required:
- job
title: BatchConfiguration
description: "Configuration for a batch.\n\nExample:\n {\n \"job\": {\n \"type\": \"parse_v2\",\n \"configuration_id\": \"cfg-PARSE_AGENTIC\"\n }\n }\n\nThis wraps the product configuration ID to run over the source directory.\nUse a built-in preset ID when available, or create/reuse a product\nconfiguration through the generic configurations API before creating the\nbatch."
BatchQueryResponse:
properties:
items:
items:
$ref: '#/components/schemas/BatchResponse'
type: array
title: Items
description: The list of items.
next_page_token:
anyOf:
- type: string
- type: 'null'
title: Next Page Token
description: A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.
total_size:
anyOf:
- type: integer
- type: 'null'
title: Total Size
description: The total number of items available. This is only populated when specifically requested. The value may be an estimate and can be used for display purposes only.
type: object
required:
- items
title: BatchQueryResponse
description: Paginated list of batches.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer