Using the REST API

Tip

For most use cases, we recommend using the Python or TypeScript SDK instead of the REST API directly.

Note

Enterprise: attribute extraction usage to a team, environment, or customer by passing a Usage-Tags header on the extract request. See Usage Tags.

Quickstart

1. Upload a document

Upload a document using the Upload API.

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/files' \
  -H 'Content-Type: multipart/form-data' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -F 'file=@/path/to/file' \
  -F purpose='extract'

Save the returned id (e.g. dfl-xxxxxxxx-...) — you’ll use it as file_input below.

Tip

The file_input field also accepts a LlamaParse job ID (pjb-xxxxxxxx-...). If you’ve already parsed a document with LlamaParse, you can pass the parse job ID directly to skip re-parsing and save time and credits. See the SDK guide or Batch Extraction Cookbook for examples.

2. Run an extraction job

Submit an extraction job with your schema and configuration inline. No agent creation needed — just provide your data_schema and options directly.

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v2/extract?project_id={PROJECT_ID}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "file_input": "{FILE_ID}",
    "configuration": {
        "tier": "agentic",
        "version": "2026-03-31",
        "extraction_target": "per_doc",
        "data_schema": {
            "type": "object",
            "properties": {
                "company_name": {
                    "type": "string",
                    "description": "Name of the company"
                },
                "revenue": {
                    "type": "number",
                    "description": "Annual revenue in USD"
                },
                "fiscal_year": {
                    "type": "integer",
                    "description": "Fiscal year of the report"
                }
            }
        },
        "cite_sources": true,
        "confidence_scores": false,
        "system_prompt": "Focus on the most recent fiscal year if multiple are present"
    }
}'

Tip: The tier field maps to UI tiers — cost_effective = Cost Effective, agentic = Agentic. Set version to a date such as 2026-03-31 to pin behavior; the date resolves to the most recent available extract version at or before that date. See Tiers and versions for details.

3. Poll for job status

Jobs are processed asynchronously. Poll for the status using the job id from the response.

curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v2/extract/{JOB_ID}?project_id={PROJECT_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

When status is COMPLETED, the extract_result field contains your extracted data.

4. Get results with metadata

To include extraction metadata (citations, confidence scores) and usage stats, use the expand parameter:

curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v2/extract/{JOB_ID}?project_id={PROJECT_ID}&expand=extract_metadata&expand=metadata' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

The endpoint accepts three expand values, combinable in one request:

Value	What it adds
extract_metadata	Per-field metadata — citations and confidence scores
configuration	The configuration the job ran with
usage	Credits billed against the job

5. Check the credits a job billed

expand=usage returns the credits billed for the extraction (extract_credits), for the parse job that produced the document text (parse_credits), and their sum (credits):

curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v2/extract/{JOB_ID}?project_id={PROJECT_ID}&expand=usage' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

{
  "id": "ext-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "COMPLETED",
  "usage": {
    "credits": 75.0,
    "extract_credits": 45.0,
    "parse_credits": 30.0
  }
}

One parse job can back several extract jobs — running two schemas over the same file_input — and each reports that same parse_credits. To total across jobs, sum extract_credits and count the parse once.

Any component reads null until billing records it, which can trail job completion. Poll again rather than reading null as zero. For plan credits and organization-wide usage, see Billing and Usage.

Configuration options

The configuration object supports many options, see the full API reference for all configuration parameters.

Legacy v1 API

If you need to use the v1 agent-based API, select the v1 toggle at the top of the sidebar to switch to Extract v1 documentation.

Full API documentation

See all available endpoints in the full API documentation.