---
title: Using the REST API | Developer Documentation
description: Guide on how to use the LlamaExtract v2 REST API for programmatic data extraction, including uploading documents, running extraction jobs, and retrieving results.
---

Tip

For most use cases, we recommend using the [Python or TypeScript SDK](../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](/llamaparse/general/usage_tags/index.md).

## Quickstart

### 1. Upload a document

Upload a document using the [Upload API](https://developers.llamaindex.ai/reference/resources/files/methods/create/).

Terminal window

```
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](../sdk#extraction-from-a-parse-job-id) or [Batch Extraction Cookbook](../examples/batch_extraction_cookbook#parse-then-extract) 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.

Terminal window

```
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": "2.5",
        "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 version name such as `2.5`, or `latest`. See [Versions](../guides/configuring-extract/#versions).

### 3. Poll for job status

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

Terminal window

```
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:

Terminal window

```
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`):

Terminal window

```
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](/llamaparse/general/billing/index.md).

## Configuration options

The `configuration` object supports many options, see the full [API reference for all configuration parameters](https://developers.llamaindex.ai/reference/resources/extract/#\(resource\)%20extract%20%3E%20\(model\)%20extract_configuration%20%3E%20\(schema\)).

## 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](https://developers.llamaindex.ai/reference/resources/extract/).