Parse File

$ llamacloud-prod parsing create

POST/api/v2/parse

Parse a file by file ID or URL.

Provide either file_id (a previously uploaded file) or source_url (a publicly accessible URL). Configure parsing with options like tier, target_pages, and lang.

Tiers

fast — rule-based, cheapest, no AI
cost_effective — balanced speed and quality
agentic — full AI-powered parsing
agentic_plus — premium AI with specialized features

The job runs asynchronously. Poll GET /parse/{job_id} with expand=text or expand=markdown to retrieve results.

ParametersExpand Collapse

--tier: "fast" or "cost_effective" or "agentic" or "agentic_plus"

Body param: Parsing tier: 'fast' (rule-based, cheapest), 'cost_effective' (balanced), 'agentic' (AI-powered with custom prompts), or 'agentic_plus' (premium AI with highest accuracy)

--version: "2025-12-11" or "2025-12-18" or "2025-12-31" or 40 more or string

Body param: Tier version. Use 'latest' for the current stable version, or specify a specific version (e.g., '1.0', '2.0') for reproducible results

--organization-id: optional string

Query param

--project-id: optional string

Query param

--agentic-options: optional object { custom_prompt }

Body param: Options for AI-powered parsing tiers (cost_effective, agentic, agentic_plus).

These options customize how the AI processes and interprets document content. Only applicable when using non-fast tiers.

--client-name: optional string

Body param: Identifier for the client/application making the request. Used for analytics and debugging. Example: 'my-app-v2'

--crop-box: optional object { bottom, left, right, top }

Body param: Crop boundaries to process only a portion of each page. Values are ratios 0-1 from page edges

--disable-cache: optional boolean

Body param: Bypass result caching and force re-parsing. Use when document content may have changed or you need fresh results

--fast-options: optional unknown

Body param: Options for fast tier parsing (rule-based, no AI).

Fast tier uses deterministic algorithms for text extraction without AI enhancement. It's the fastest and most cost-effective option, best suited for simple documents with standard layouts. Currently has no configurable options but reserved for future expansion.

--file-id: optional string

Body param: ID of an existing file in the project to parse. Mutually exclusive with source_url

--http-proxy: optional string

Body param: HTTP/HTTPS proxy for fetching source_url. Ignored if using file_id

--input-options: optional object { html, pdf, presentation, spreadsheet }

Body param: Format-specific options (HTML, PDF, spreadsheet, presentation). Applied based on detected input file type

--output-options: optional object { extract_printed_page_number, images_to_save, markdown, 2 more }

Body param: Output formatting options for markdown, text, and extracted images

--page-ranges: optional object { max_pages, target_pages }

Body param: Page selection: limit total pages or specify exact pages to process

--processing-control: optional object { job_failure_conditions, timeouts }

Body param: Job execution controls including timeouts and failure thresholds

--processing-options: optional object { aggressive_table_extraction, auto_mode_configuration, cost_optimizer, 4 more }

Body param: Document processing options including OCR, table extraction, and chart parsing

--source-url: optional string

Body param: Public URL of the document to parse. Mutually exclusive with file_id

--webhook-configuration: optional array of object { webhook_events, webhook_headers, webhook_url }

Body param: Webhook endpoints for job status notifications. Multiple webhooks can be configured for different events or services

ReturnsExpand Collapse

ParsingNewResponse: object { id, project_id, status, 5 more }

A parse job.

id: string

Unique parse job identifier

project_id: string

Project this job belongs to

status: "PENDING" or "RUNNING" or "COMPLETED" or 2 more

Current job status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED

"PENDING"

"RUNNING"

"COMPLETED"

"FAILED"

"CANCELLED"

created_at: optional string

Creation datetime

error_message: optional string

Error details when status is FAILED

name: optional string

Optional display name for this parse job

tier: optional string

Parsing tier used for this job

updated_at: optional string

Update datetime

Parse File

llamacloud-prod parsing create \
  --api-key 'My API Key' \
  --tier fast \
  --version "'2025-12-11'"

{
  "id": "pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "project_id": "prj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "PENDING",
  "created_at": "2019-12-27T18:11:19.117Z",
  "error_message": "error_message",
  "name": "Q4 Financial Report",
  "tier": "fast",
  "updated_at": "2019-12-27T18:11:19.117Z"
}

Returns Examples

{
  "id": "pjb-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "project_id": "prj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "PENDING",
  "created_at": "2019-12-27T18:11:19.117Z",
  "error_message": "error_message",
  "name": "Q4 Financial Report",
  "tier": "fast",
  "updated_at": "2019-12-27T18:11:19.117Z"
}