API Reference

Parsing

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

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" or string

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: "latest" or "2026-06-26" or "2026-06-18" or "2025-12-11" or string

Body param: Version for the selected tier. Use latest, or pin one of that tier’s dated versions.

Current latest by tier:

• fast: 2025-12-11
• cost_effective: 2026-06-26
• agentic: 2026-06-18
• agentic_plus: 2026-06-18

Full list: GET /api/v2/parse/versions.

--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’

--configuration-id: optional string

Body param: ID of a saved parse configuration. When set, tier and version default to the saved configuration’s values — omit them or pass 'configured'.

--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, image, pdf, 2 more }

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

--output-options: optional object { additional_outputs, extract_printed_page_number, granular_bboxes, 4 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

--user-metadata: optional map[string]

Body param: Arbitrary key/value tags to attach to this job. Returned when retrieving the job. Not searchable. Limits apply to the number of entries and the length of keys and values; oversized metadata is rejected.

--webhook-configuration-id: optional array of string

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

--webhook-configuration: optional array of object { webhook_events, webhook_headers, webhook_output_format, 2 more }

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, 6 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

user_metadata: optional map[string]

Key/value tags associated with this job.

Parse File

CLI Tool

HTTP

TypeScript

Python

Java

Go

CLI Tool

llamacloud-prod parsing create \
  --api-key 'My API Key' \
  --tier fast \
  --version latest

200 example

{
  "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",
  "user_metadata": {
    "owner": "jerry",
    "team": "research"
  }
}

Returns Examples

200 example

{
  "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",
  "user_metadata": {
    "owner": "jerry",
    "team": "research"
  }
}