API Reference

Batches

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create Batch

client.Batches.New(ctx, params) (*BatchNewResponse, error)

POST/api/v2/batches

Create a batch over a source directory and start processing asynchronously.

To be notified as the batch progresses, pass webhook_configurations with inline endpoints and/or webhook_configuration_ids referencing saved configurations. Batches emit batch.pending on create, batch.running once processing starts, and a terminal batch.success or batch.error.

batch.success means the batch finished mapping every source file to a job — individual files may still have failed, so read results (with expand=results) for per-file outcomes.

Delivery order across events is not guaranteed; key on the status field in the payload rather than arrival order.

ParametersExpand Collapse

params BatchNewParams

Config param.Field[BatchNewParamsConfig]

Body param: Batch configuration snapshot to apply to this source directory.

Job BatchNewParamsConfigJob

Job to create for each file in the source directory.

ConfigurationID string

Product configuration ID or built-in preset ID matching the job type.

Type BatchNewParamsConfigJobType

Product job type to run for each source directory file.

One of the following:

const BatchNewParamsConfigJobTypeParseV2 BatchNewParamsConfigJobType = "parse_v2"

const BatchNewParamsConfigJobTypeExtractV2 BatchNewParamsConfigJobType = "extract_v2"

SourceDirectoryID param.Field[string]

Body param: Directory whose files should be processed.

OrganizationID param.Field[string]Optional

Query param

formatuuid

ProjectID param.Field[string]Optional

Query param

formatuuid

WebhookConfigurationIDs param.Field[[]string]Optional

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

WebhookConfigurations param.Field[[]BatchNewParamsWebhookConfiguration]Optional

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

WebhookEvents []stringOptional

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

One of the following:

const BatchNewParamsWebhookConfigurationWebhookEventBatchCancelled BatchNewParamsWebhookConfigurationWebhookEvent = "batch.cancelled"

const BatchNewParamsWebhookConfigurationWebhookEventBatchError BatchNewParamsWebhookConfigurationWebhookEvent = "batch.error"

const BatchNewParamsWebhookConfigurationWebhookEventBatchPending BatchNewParamsWebhookConfigurationWebhookEvent = "batch.pending"

const BatchNewParamsWebhookConfigurationWebhookEventBatchRunning BatchNewParamsWebhookConfigurationWebhookEvent = "batch.running"

const BatchNewParamsWebhookConfigurationWebhookEventBatchSuccess BatchNewParamsWebhookConfigurationWebhookEvent = "batch.success"

const BatchNewParamsWebhookConfigurationWebhookEventClassifyCancelled BatchNewParamsWebhookConfigurationWebhookEvent = "classify.cancelled"

const BatchNewParamsWebhookConfigurationWebhookEventClassifyError BatchNewParamsWebhookConfigurationWebhookEvent = "classify.error"

const BatchNewParamsWebhookConfigurationWebhookEventClassifyPartialSuccess BatchNewParamsWebhookConfigurationWebhookEvent = "classify.partial_success"

const BatchNewParamsWebhookConfigurationWebhookEventClassifyPending BatchNewParamsWebhookConfigurationWebhookEvent = "classify.pending"

const BatchNewParamsWebhookConfigurationWebhookEventClassifyRunning BatchNewParamsWebhookConfigurationWebhookEvent = "classify.running"

const BatchNewParamsWebhookConfigurationWebhookEventClassifySuccess BatchNewParamsWebhookConfigurationWebhookEvent = "classify.success"

const BatchNewParamsWebhookConfigurationWebhookEventExtractCancelled BatchNewParamsWebhookConfigurationWebhookEvent = "extract.cancelled"

const BatchNewParamsWebhookConfigurationWebhookEventExtractError BatchNewParamsWebhookConfigurationWebhookEvent = "extract.error"

const BatchNewParamsWebhookConfigurationWebhookEventExtractPartialSuccess BatchNewParamsWebhookConfigurationWebhookEvent = "extract.partial_success"

const BatchNewParamsWebhookConfigurationWebhookEventExtractPending BatchNewParamsWebhookConfigurationWebhookEvent = "extract.pending"

const BatchNewParamsWebhookConfigurationWebhookEventExtractSuccess BatchNewParamsWebhookConfigurationWebhookEvent = "extract.success"

const BatchNewParamsWebhookConfigurationWebhookEventParseCancelled BatchNewParamsWebhookConfigurationWebhookEvent = "parse.cancelled"

const BatchNewParamsWebhookConfigurationWebhookEventParseError BatchNewParamsWebhookConfigurationWebhookEvent = "parse.error"

const BatchNewParamsWebhookConfigurationWebhookEventParsePartialSuccess BatchNewParamsWebhookConfigurationWebhookEvent = "parse.partial_success"

const BatchNewParamsWebhookConfigurationWebhookEventParsePending BatchNewParamsWebhookConfigurationWebhookEvent = "parse.pending"

const BatchNewParamsWebhookConfigurationWebhookEventParseRunning BatchNewParamsWebhookConfigurationWebhookEvent = "parse.running"

const BatchNewParamsWebhookConfigurationWebhookEventParseSuccess BatchNewParamsWebhookConfigurationWebhookEvent = "parse.success"

const BatchNewParamsWebhookConfigurationWebhookEventSheetsCancelled BatchNewParamsWebhookConfigurationWebhookEvent = "sheets.cancelled"

const BatchNewParamsWebhookConfigurationWebhookEventSheetsError BatchNewParamsWebhookConfigurationWebhookEvent = "sheets.error"

const BatchNewParamsWebhookConfigurationWebhookEventSheetsPartialSuccess BatchNewParamsWebhookConfigurationWebhookEvent = "sheets.partial_success"

const BatchNewParamsWebhookConfigurationWebhookEventSheetsPending BatchNewParamsWebhookConfigurationWebhookEvent = "sheets.pending"

const BatchNewParamsWebhookConfigurationWebhookEventSheetsSuccess BatchNewParamsWebhookConfigurationWebhookEvent = "sheets.success"

const BatchNewParamsWebhookConfigurationWebhookEventSplitCancelled BatchNewParamsWebhookConfigurationWebhookEvent = "split.cancelled"

const BatchNewParamsWebhookConfigurationWebhookEventSplitError BatchNewParamsWebhookConfigurationWebhookEvent = "split.error"

const BatchNewParamsWebhookConfigurationWebhookEventSplitPending BatchNewParamsWebhookConfigurationWebhookEvent = "split.pending"

const BatchNewParamsWebhookConfigurationWebhookEventSplitProcessing BatchNewParamsWebhookConfigurationWebhookEvent = "split.processing"

const BatchNewParamsWebhookConfigurationWebhookEventSplitSuccess BatchNewParamsWebhookConfigurationWebhookEvent = "split.success"

const BatchNewParamsWebhookConfigurationWebhookEventUnmappedEvent BatchNewParamsWebhookConfigurationWebhookEvent = "unmapped_event"

WebhookHeaders map[string, string]Optional

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

WebhookOutputFormat stringOptional

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

WebhookSigningSecret stringOptional

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=’). Recompute the HMAC over the raw request body with this secret to verify the delivery is authentic.

WebhookURL stringOptional

URL to receive webhook POST notifications

ReturnsExpand Collapse

type BatchNewResponse struct{…}

A top-level batch.

Example: { “id”: “bat-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee”, “project_id”: “prj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee”, “source_directory_id”: “dir-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee”, “config”: { “job”: { “type”: “parse_v2”, “configuration_id”: “cfg-PARSE_AGENTIC” } }, “status”: “COMPLETED”, “results”: [ { “source_directory_file_id”: “dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee”, “job_reference”: { “type”: “parse_v2”, “id”: “pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee” }, “error_message”: null } ] }

Batch-level FAILED means the orchestration failed and cannot provide a reliable per-file result set. results is only populated when explicitly requested with expand=results and may be null while a batch is still running.

ID string

Unique identifier

Config BatchNewResponseConfig

Batch configuration snapshot.

Job BatchNewResponseConfigJob

Job to create for each file in the source directory.

ConfigurationID string

Product configuration ID or built-in preset ID matching the job type.

Type BatchNewResponseConfigJobType

Product job type to run for each source directory file.

One of the following:

const BatchNewResponseConfigJobTypeParseV2 BatchNewResponseConfigJobType = "parse_v2"

const BatchNewResponseConfigJobTypeExtractV2 BatchNewResponseConfigJobType = "extract_v2"

ProjectID string

Project this batch belongs to.

SourceDirectoryID string

Directory being processed.

Status BatchNewResponseStatus

Current batch status.

One of the following:

const BatchNewResponseStatusCancelled BatchNewResponseStatus = "CANCELLED"

const BatchNewResponseStatusCompleted BatchNewResponseStatus = "COMPLETED"

const BatchNewResponseStatusFailed BatchNewResponseStatus = "FAILED"

const BatchNewResponseStatusPending BatchNewResponseStatus = "PENDING"

const BatchNewResponseStatusRunning BatchNewResponseStatus = "RUNNING"

const BatchNewResponseStatusThrottled BatchNewResponseStatus = "THROTTLED"

CreatedAt TimeOptional

Creation datetime

formatdate-time

Results []BatchNewResponseResultOptional

Expanded per-file result mappings. Null unless requested with expand=results, or while the batch is still running.

SourceDirectoryFileID string

Source directory file processed by this batch.

ErrorMessage stringOptional

Batch-level mapping error if the system could not create or associate a job for this source file.

JobReference BatchNewResponseResultJobReferenceOptional

Reference to a job produced by a batch.

Example: { “type”: “parse_v2”, “id”: “pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee” }

ID string

Job ID, such as a parse job ID.

Type BatchNewResponseResultJobReferenceType

Type of job produced for the file.

One of the following:

const BatchNewResponseResultJobReferenceTypeParseV2 BatchNewResponseResultJobReferenceType = "parse_v2"

const BatchNewResponseResultJobReferenceTypeExtractV2 BatchNewResponseResultJobReferenceType = "extract_v2"

UpdatedAt TimeOptional

Update datetime

formatdate-time

Create Batch

Go

HTTP

TypeScript

Python

Go

Java

C#

CLI Tool

package main

import (
  "context"
  "fmt"

  "github.com/run-llama/llama-parse-go"
  "github.com/run-llama/llama-parse-go/option"
)

func main() {
  client := llamacloud.NewClient(
    option.WithAPIKey("My API Key"),
  )
  batch, err := client.Batches.New(context.TODO(), llamacloud.BatchNewParams{
    Config: llamacloud.BatchNewParamsConfig{
      Job: llamacloud.BatchNewParamsConfigJob{
        ConfigurationID: "cfg-PARSE_AGENTIC",
        Type: llamacloud.BatchNewParamsConfigJobTypeParseV2,
      },
    },
    SourceDirectoryID: "dir-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", batch.ID)
}

200 example

{
  "id": "id",
  "config": {
    "job": {
      "configuration_id": "cfg-PARSE_AGENTIC",
      "type": "parse_v2"
    }
  },
  "project_id": "project_id",
  "source_directory_id": "source_directory_id",
  "status": "CANCELLED",
  "created_at": "2019-12-27T18:11:19.117Z",
  "results": [
    {
      "source_directory_file_id": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "error_message": "error_message",
      "job_reference": {
        "id": "pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "type": "parse_v2"
      }
    }
  ],
  "updated_at": "2019-12-27T18:11:19.117Z"
}

Returns Examples

200 example

{
  "id": "id",
  "config": {
    "job": {
      "configuration_id": "cfg-PARSE_AGENTIC",
      "type": "parse_v2"
    }
  },
  "project_id": "project_id",
  "source_directory_id": "source_directory_id",
  "status": "CANCELLED",
  "created_at": "2019-12-27T18:11:19.117Z",
  "results": [
    {
      "source_directory_file_id": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "error_message": "error_message",
      "job_reference": {
        "id": "pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "type": "parse_v2"
      }
    }
  ],
  "updated_at": "2019-12-27T18:11:19.117Z"
}