## Create Batch

`batches.create(BatchCreateParams**kwargs)  -> BatchCreateResponse`

**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.

### Parameters

- `config: Config`

  Batch configuration snapshot to apply to this source directory.

  - `job: ConfigJob`

    Job to create for each file in the source directory.

    - `configuration_id: str`

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

    - `type: Literal["parse_v2", "extract_v2"]`

      Product job type to run for each source directory file.

      - `"parse_v2"`

      - `"extract_v2"`

- `source_directory_id: str`

  Directory whose files should be processed.

- `organization_id: Optional[str]`

- `project_id: Optional[str]`

- `webhook_configuration_ids: Optional[Sequence[str]]`

  IDs of saved webhook configurations to notify for this job.

- `webhook_configurations: Optional[Iterable[WebhookConfiguration]]`

  Outbound webhook endpoints to notify on job status changes

  - `webhook_events: Optional[List[Literal["batch.cancelled", "batch.error", "batch.pending", 36 more]]]`

    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.running"`

    - `"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: Optional[Dict[str, str]]`

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

  - `webhook_output_format: Optional[str]`

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

  - `webhook_signing_secret: Optional[str]`

    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: Optional[str]`

    URL to receive webhook POST notifications

### Returns

- `class BatchCreateResponse: …`

  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: str`

    Unique identifier

  - `config: Config`

    Batch configuration snapshot.

    - `job: ConfigJob`

      Job to create for each file in the source directory.

      - `configuration_id: str`

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

      - `type: Literal["parse_v2", "extract_v2"]`

        Product job type to run for each source directory file.

        - `"parse_v2"`

        - `"extract_v2"`

  - `project_id: str`

    Project this batch belongs to.

  - `source_directory_id: str`

    Directory being processed.

  - `status: Literal["CANCELLED", "COMPLETED", "FAILED", 3 more]`

    Current batch status.

    - `"CANCELLED"`

    - `"COMPLETED"`

    - `"FAILED"`

    - `"PENDING"`

    - `"RUNNING"`

    - `"THROTTLED"`

  - `created_at: Optional[datetime]`

    Creation datetime

  - `results: Optional[List[Result]]`

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

    - `source_directory_file_id: str`

      Source directory file processed by this batch.

    - `error_message: Optional[str]`

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

    - `job_reference: Optional[ResultJobReference]`

      Reference to a job produced by a batch.

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

      - `id: str`

        Job ID, such as a parse job ID.

      - `type: Literal["parse_v2", "extract_v2"]`

        Type of job produced for the file.

        - `"parse_v2"`

        - `"extract_v2"`

  - `updated_at: Optional[datetime]`

    Update datetime

### Example

```python
import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
batch = client.batches.create(
    config={
        "job": {
            "configuration_id": "cfg-PARSE_AGENTIC",
            "type": "parse_v2",
        }
    },
    source_directory_id="dir-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
)
print(batch.id)
```

#### Response

```json
{
  "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"
}
```
