Llama Cloud Python SDK

Warnings

• breaking The v2.0.0 release introduced significant breaking changes, including the removal of the v1 extraction resource and a restructure of metadata. If you were using `extraction` features prior to v2.0.0, your code will need updates.
  Fix: Review the official Llama Cloud API documentation for updated `extraction` and `parse` endpoint usage and new metadata structures. Specifically, refer to the 'Migration Guide: Parse Upload Endpoint v1 to v2' for detailed changes.
• breaking The `llama-cloud-services` package is deprecated and will no longer be maintained after May 1, 2026. This older SDK has different import paths and API surface areas.
  Fix: Migrate your codebase to use the `llama-cloud` package (version >=1.0) and update all imports and API calls accordingly. The new SDK provides improved performance and active development.
• gotcha Hardcoding API keys directly in your application code is a security risk. API keys are user and project-scoped.
  Fix: Always store your `LLAMA_CLOUD_API_KEY` in environment variables or a secure key management service. The SDK automatically picks up `LLAMA_CLOUD_API_KEY` from environment variables, or it can be passed via the `api_key` parameter during client initialization using `os.environ.get('LLAMA_CLOUD_API_KEY')`.
• gotcha LlamaParse API v2 introduced structured configuration objects (`input_options`, `output_options`, `processing_options`) instead of a flat list of parameters from v1. Old parameter names or structures from v1 will not work with v2 endpoints.
  Fix: Consult the LlamaParse API v2 documentation for the correct use of `tier` and the new configuration objects when calling `client.parsing.create()` or `client.parsing.parse()`.

Install

• pip install llama-cloud Install stable version

Imports

• LlamaCloud

  from llama_cloud import LlamaCloud

• AsyncLlamaCloud

  from llama_cloud import AsyncLlamaCloud

• APIError

  from llama_cloud import APIError

  While `import llama_cloud` works, importing `APIError` directly is cleaner for exception handling.

Quickstart

Initializes the Llama Cloud client using an API key from environment variables and demonstrates how to create a document parsing job. For actual usage, replace `dummy_file_id` with an ID obtained from uploading a file via `client.files.create()`.

import os
from llama_cloud import LlamaCloud
from pathlib import Path

# Ensure LLAMA_CLOUD_API_KEY is set in your environment variables
# e.g., os.environ['LLAMA_CLOUD_API_KEY'] = 'llx-...' or using a .env file
client = LlamaCloud(
    api_key=os.environ.get('LLAMA_CLOUD_API_KEY', '')
)

# Example: Upload a dummy file and create a parsing job
# Replace with a real file path for actual usage
# file_path = Path("path/to/your/document.pdf")
# with open(file_path, "rb") as f:
#     file_obj = client.files.create(
#         file=(file_path.name, f.read(), "application/pdf"),
#         purpose="parse",
#     )

# For demonstration, simulate a file_id to create a parsing job
# In a real scenario, file_id would come from client.files.create() or an existing file.
dummy_file_id = "your-example-file-id" # Replace with actual file_id if uploading

if not dummy_file_id:
    print("Please provide a valid file_id or upload a file first.")
else:
    try:
        job = client.parsing.create(
            tier="agentic", # or "fast", "cost_effective"
            version="latest",
            file_id=dummy_file_id,
            # For example, to get markdown output:
            output_options={
                "markdown": {
                    "tables": {
                        "output_tables_as_markdown": True
                    }
                }
            },
            expand=["markdown"]
        )
        print(f"Created parsing job with ID: {job.id}")
        # You would typically poll the job status and retrieve results here
        # For example, using client.parsing.get_job_result(job.id)
    except Exception as e:
        print(f"An error occurred: {e}")