Llama Cloud Python SDK

The official Python SDK for LlamaParse - the enterprise platform for agentic OCR and document processing.

With this SDK, create powerful workflows across many features:

• Parse - Agentic OCR and parsing for 130+ formats
• Extract - Structured data extraction with custom schemas
• Classify - Document categorization with natural-language rules
• Agents - Deploy document agents as APIs
• Index - Document ingestion and embedding for RAG

Documentation

• Get an API Key
• Getting Started Guide
• Full API Reference

Installation

pip install llama_cloud

Quick Start

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
)

# Parse a document
job = client.parsing.create(
    tier="agentic",
    version="latest",
    file_id="your-file-id",
)

print(job.id)

File Uploads

from pathlib import Path
from llama_cloud import LlamaCloud

client = LlamaCloud()

# Upload using a Path
client.files.create(
    file=Path("/path/to/document.pdf"),
    purpose="parse",
)

# Or using bytes with a tuple of (filename, contents, media_type)
client.files.create(
    file=("document.txt", b"content", "text/plain"),
    purpose="parse",
)

Async Usage

import asyncio
from llama_cloud import AsyncLlamaCloud

client = AsyncLlamaCloud()


async def main():
    job = await client.parsing.create(
        tier="agentic",
        version="latest",
        file_id="your-file-id",
    )
    print(job.id)


asyncio.run(main())

MCP Server

Use the Llama Cloud MCP Server to enable AI assistants to interact with the API:

Error Handling

When the API returns a non-success status code, an APIError subclass is raised:

import llama_cloud
from llama_cloud import LlamaCloud

client = LlamaCloud()

try:
    client.pipelines.list(project_id="my-project-id")
except llama_cloud.APIError as e:
    print(e.status_code)  # 400
    print(e.__class__.__name__)  # BadRequestError

Status Code	Error Type
400	BadRequestError
401	AuthenticationError
403	PermissionDeniedError
404	NotFoundError
422	UnprocessableEntityError
429	RateLimitError
>=500	InternalServerError
N/A	APIConnectionError

Retries and Timeouts

The SDK automatically retries requests 2 times on connection errors, timeouts, rate limits, and 5xx errors. Requests timeout after 1 minute by default. Functions that combine multiple API calls (e.g. client.parsing.parse()) will have larger timeouts by default to account for the multiple requests and polling.

client = LlamaCloud(
    max_retries=0,  # Disable retries (default: 2)
    timeout=30.0,  # 30 second timeout (default: 1 minute)
)

Pagination

List methods support auto-pagination with for loops:

for run in client.extraction.runs.list(
    extraction_agent_id="agent-id",
    limit=20,
):
    print(run)

Or fetch one page at a time:

page = client.extraction.runs.list(extraction_agent_id="agent-id", limit=20)
for run in page.items:
    print(run)

while page.has_next_page():
    page = page.get_next_page()

Logging

Configure logging via the LLAMA_CLOUD_LOG environment variable or the log option:

client = LlamaCloud(
    log="debug",  # "debug" | "info" | "warn" | "error" | "off"
)

Requirements

• Python 3.9+

Contributing

See CONTRIBUTING.md.