REST API Guide

Guide

Parse

Guides

Parse REST API endpoints, request/response shapes, expand values, and presigned URL patterns.

For the complete SDK and API documentation, see the Parse API Reference →

This page covers REST API usage patterns: endpoint overview, request examples, response shapes, and the expand parameter quick-reference.

Endpoints

Method	URL	Use case
`POST /api/v2/parse`	Parse a file by ID or URL (JSON body)
`GET /api/v2/parse`	List and filter parse jobs with pagination
`GET /api/v2/parse/{job_id}`	Check job status and retrieve results

Required header: Authorization: Bearer YOUR_API_KEY on all endpoints.

Creating a parse job

Send a JSON body with file_id (or source_url), tier, version, and any options:

curl -X POST 'https://api.cloud.llamaindex.ai/api/v2/parse' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  --data '{
    "file_id": "<file_id>",
    "tier": "agentic",
    "version": "latest"
  }'

The response includes a job.id. Use it to retrieve results with the expand query parameter (see Retrieving results below). See Configuring Parse for every available option.

Listing jobs

curl 'https://api.cloud.llamaindex.ai/api/v2/parse?page_size=10&status=COMPLETED' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

Query parameters:

Parameter	Type	Description
`page_size`	integer	Max items per page (optional)
`page_token`	string	Token for the next page (from a previous response)
`status`	string	Filter: `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`

Response:

{
  "items": [
    {
      "id": "job-uuid-1",
      "project_id": "project-uuid",
      "status": "COMPLETED",
      "error_message": null
    }
  ],
  "next_page_token": "eyJsYXN0X2lkIjogImpvYi...",
  "total_size": 42
}

Retrieving results

curl 'https://api.cloud.llamaindex.ai/api/v2/parse/{job_id}?expand=markdown,items,metadata' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

The response always includes a job object with id, project_id, status, and error_message. Additional fields depend on the expand parameter.

Expand values

Value	What it returns
`text`	Plain text per page
`markdown`	Markdown per page
`items`	Structured JSON items (tables, headings, paragraphs per page)
`metadata`	Page-level metadata (confidence, speaker notes, cost_optimized, etc.)
`job_metadata`	Usage and processing details
`text_full`	Full plain text as a single string (all pages concatenated)
`markdown_full`	Full markdown as a single string (all pages concatenated)
`text_content_metadata`	Text file presigned download URL
`markdown_content_metadata`	Markdown file presigned download URL
`items_content_metadata`	Items file presigned download URL
`metadata_content_metadata`	Metadata file presigned download URL
`text_full_content_metadata`	Full text file presigned download URL
`markdown_full_content_metadata`	Full markdown file presigned download URL
`xlsx_content_metadata`	XLSX file presigned download URL
`output_pdf_content_metadata`	Output PDF presigned download URL
`images_content_metadata`	Images metadata with per-image presigned URLs

Combine multiple values: ?expand=markdown,items,images_content_metadata

For detailed guidance on choosing expand values, see Retrieving Results.

Content metadata response shapes

When requesting *_content_metadata expand values, the response includes presigned URLs for direct download:

XLSX and PDF:

{
  "result_content_metadata": {
    "xlsx": {
      "size_bytes": 15234,
      "exists": true,
      "presigned_url": "https://s3.amazonaws.com/..."
    },
    "outputPDF": {
      "size_bytes": 102400,
      "exists": true,
      "presigned_url": "https://s3.amazonaws.com/..."
    }
  }
}

Images:

{
  "images_content_metadata": {
    "total_count": 3,
    "images": [
      {
        "index": 0,
        "filename": "image_0.png",
        "content_type": "image/png",
        "size_bytes": 12345,
        "presigned_url": "https://s3.amazonaws.com/..."
      }
    ]
  }
}

You can filter images with the image_filenames query parameter:

curl 'https://api.cloud.llamaindex.ai/api/v2/parse/{job_id}?expand=images_content_metadata&image_filenames=image_0.png,image_1.jpg' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

Presigned URLs are temporary. Download files promptly after retrieving them, or call the endpoint again for fresh URLs.

Error responses

v2 returns structured validation errors:

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["tier"],
      "msg": "Unsupported tier: invalid_tier. Must be one of: fast, cost_effective, agentic, agentic_plus",
      "input": {}
    }
  ]
}