# Batches ## Create Batch `$ llamacloud-prod batches create` **post** `/api/v2/batches` Create a batch over a source directory and start processing asynchronously. ### Parameters - `--config: object { job }` Body param: Batch configuration snapshot to apply to this source directory. - `--source-directory-id: string` Body param: Directory whose files should be processed. - `--organization-id: optional string` Query param - `--project-id: optional string` Query param ### Returns - `BatchNewResponse: object { id, config, project_id, 5 more }` 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-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "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 or before result mappings are available. - `id: string` Unique identifier - `config: object { job }` Batch configuration snapshot. - `job: object { configuration_id, type }` Job to create for each file in the source directory. - `configuration_id: string` Saved product configuration ID matching the job type. - `type: "parse_v2" or "extract_v2"` Product job type to run for each source directory file. - `"parse_v2"` - `"extract_v2"` - `project_id: string` Project this batch belongs to. - `source_directory_id: string` Directory being processed. - `status: "PENDING" or "THROTTLED" or "RUNNING" or 3 more` Current batch status. - `"PENDING"` - `"THROTTLED"` - `"RUNNING"` - `"COMPLETED"` - `"FAILED"` - `"CANCELLED"` - `created_at: optional string` Creation datetime - `results: optional array of object { source_directory_file_id, error_message, job_reference }` Expanded per-file result mappings. Null unless requested with expand=results, or until result mappings are available. - `source_directory_file_id: string` Source directory file processed by this batch. - `error_message: optional string` Batch-level mapping error if the system could not create or associate a job for this source file. - `job_reference: optional object { id, type }` 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: "parse_v2" or "extract_v2"` Type of job produced for the file. - `"parse_v2"` - `"extract_v2"` - `updated_at: optional string` Update datetime ### Example ```cli llamacloud-prod batches create \ --api-key 'My API Key' \ --config '{job: {configuration_id: cfg-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee, type: parse_v2}}' \ --source-directory-id dir-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ``` #### Response ```json { "id": "id", "config": { "job": { "configuration_id": "cfg-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "parse_v2" } }, "project_id": "project_id", "source_directory_id": "source_directory_id", "status": "PENDING", "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" } ``` ## List Batches `$ llamacloud-prod batches list` **get** `/api/v2/batches` List batches for the current project. ### Parameters - `--created-at-on-or-after: optional string` - `--created-at-on-or-before: optional string` - `--organization-id: optional string` - `--page-size: optional number` - `--page-token: optional string` - `--project-id: optional string` - `--source-directory-id: optional string` - `--status: optional "PENDING" or "THROTTLED" or "RUNNING" or 3 more` ### Returns - `BatchQueryResponse: object { items, next_page_token, total_size }` Paginated list of batches. - `items: array of object { id, config, project_id, 5 more }` The list of items. - `id: string` Unique identifier - `config: object { job }` Batch configuration snapshot. - `job: object { configuration_id, type }` Job to create for each file in the source directory. - `configuration_id: string` Saved product configuration ID matching the job type. - `type: "parse_v2" or "extract_v2"` Product job type to run for each source directory file. - `"parse_v2"` - `"extract_v2"` - `project_id: string` Project this batch belongs to. - `source_directory_id: string` Directory being processed. - `status: "PENDING" or "THROTTLED" or "RUNNING" or 3 more` Current batch status. - `"PENDING"` - `"THROTTLED"` - `"RUNNING"` - `"COMPLETED"` - `"FAILED"` - `"CANCELLED"` - `created_at: optional string` Creation datetime - `results: optional array of object { source_directory_file_id, error_message, job_reference }` Expanded per-file result mappings. Null unless requested with expand=results, or until result mappings are available. - `source_directory_file_id: string` Source directory file processed by this batch. - `error_message: optional string` Batch-level mapping error if the system could not create or associate a job for this source file. - `job_reference: optional object { id, type }` 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: "parse_v2" or "extract_v2"` Type of job produced for the file. - `"parse_v2"` - `"extract_v2"` - `updated_at: optional string` Update datetime - `next_page_token: optional string` 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: optional number` 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. ### Example ```cli llamacloud-prod batches list \ --api-key 'My API Key' ``` #### Response ```json { "items": [ { "id": "id", "config": { "job": { "configuration_id": "cfg-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "parse_v2" } }, "project_id": "project_id", "source_directory_id": "source_directory_id", "status": "PENDING", "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" } ], "next_page_token": "next_page_token", "total_size": 0 } ``` ## Get Batch `$ llamacloud-prod batches get` **get** `/api/v2/batches/{batch_id}` Get a batch by ID. ### Parameters - `--batch-id: string` - `--expand: optional array of string` Fields to expand. Supported value: results. - `--organization-id: optional string` - `--project-id: optional string` ### Returns - `BatchGetResponse: object { id, config, project_id, 5 more }` 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-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "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 or before result mappings are available. - `id: string` Unique identifier - `config: object { job }` Batch configuration snapshot. - `job: object { configuration_id, type }` Job to create for each file in the source directory. - `configuration_id: string` Saved product configuration ID matching the job type. - `type: "parse_v2" or "extract_v2"` Product job type to run for each source directory file. - `"parse_v2"` - `"extract_v2"` - `project_id: string` Project this batch belongs to. - `source_directory_id: string` Directory being processed. - `status: "PENDING" or "THROTTLED" or "RUNNING" or 3 more` Current batch status. - `"PENDING"` - `"THROTTLED"` - `"RUNNING"` - `"COMPLETED"` - `"FAILED"` - `"CANCELLED"` - `created_at: optional string` Creation datetime - `results: optional array of object { source_directory_file_id, error_message, job_reference }` Expanded per-file result mappings. Null unless requested with expand=results, or until result mappings are available. - `source_directory_file_id: string` Source directory file processed by this batch. - `error_message: optional string` Batch-level mapping error if the system could not create or associate a job for this source file. - `job_reference: optional object { id, type }` 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: "parse_v2" or "extract_v2"` Type of job produced for the file. - `"parse_v2"` - `"extract_v2"` - `updated_at: optional string` Update datetime ### Example ```cli llamacloud-prod batches get \ --api-key 'My API Key' \ --batch-id batch_id ``` #### Response ```json { "id": "id", "config": { "job": { "configuration_id": "cfg-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "parse_v2" } }, "project_id": "project_id", "source_directory_id": "source_directory_id", "status": "PENDING", "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" } ```