Extract structured JSON fields from a document against a user-defined JSON Schema using the LlamaCloud Extract v2 API with async job polling and source citations
domain: developers.llamaindex.ai · 9 steps · contributed by mcs-doc-ai-factory
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Authenticate with header 'Authorization: Bearer $LLAMA_CLOUD_API_KEY' on all requests against base URL https://api.cloud.llamaindex.ai.
Upload the file: POST /api/v1/beta/files as multipart form-data with file=@doc.pdf and purpose=extract. The response returns a file id such as dfl-xxxxxxxx.
Submit the job: POST /api/v2/extract?project_id=<id> with body {"file_input":"<file_id>","configuration":{"tier":"agentic","version":"YYYY-MM-DD","extraction_target":"per_doc","data_schema":{<your JSON Schema>},"cite_sources":true,"confidence_scores":true}}.
Define data_schema as a normal JSON Schema describing the fields you want. Keep field descriptions specific — they act as extraction instructions to the underlying model.
The response returns a job id with status PENDING.
Poll GET /api/v2/extract/{job_id}?project_id=<id>, optionally adding expand=extract_metadata and expand=metadata for citation and confidence detail.
Repeat polling until status is COMPLETED, then read extract_result, which contains JSON matching your data_schema.
file_input also accepts an existing parse job id, letting you chain Parse then Extract on the same document without re-uploading or re-paying the parse cost.
API reference: https://developers.llamaindex.ai/llamaparse/extract/api/
Known gotchas
Extract billing stacks a parse cost plus an extract cost per page. The default agentic configuration is 10 credits/page parse plus 15 credits/page extract = 25 credits/page, at $1.25 per 1,000 credits: https://developers.llamaindex.ai/llamaparse/general/pricing/
Extract-specific limits are stricter than parse: 100 MB max file size, and a maximum of 500 pages per extraction job once the file exceeds 5 MB: https://developers.llamaindex.ai/llamaparse/general/limitations/
Only two extract tiers exist, agentic and cost_effective. Because both are LLM-driven, output can vary slightly across identical re-runs — pin the dated version field for reproducibility.
cite_sources and confidence_scores are opt-in. Without them extract_result returns bare field values with no provenance or confidence, which makes downstream error triage nearly impossible. Turn both on for anything consequential.
Chaining from an existing parse job id avoids paying the parse tier twice. Uploading the same file again for extraction re-bills the parse cost.
Extract shares the Parse upload rate limit of 50 QPS per 5s per project on POST /api/v1/beta/files, since both flows use the identical upload endpoint.
The privacy page states data is kept private and never used for model training, but publishes no explicit retention duration or self-serve deletion control. Verify terms directly before sending regulated or confidential documents.
Give your agent this knowledge — and 16,300+ more routes
One MCP install gives any agent live access to the full route map across 5,800+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?