---
title: "Create Extract Job"
method: POST
path: "/api/v2/extract"
tags: ["V2", "Extract"]
---

# Create Extract Job

`POST /api/v2/extract`

Create an extraction job.

Extracts structured data from a document using either a saved
configuration or an inline JSON Schema.

## Input

Provide exactly one of:
- `configuration_id` — reference a saved extraction config
- `configuration` — inline configuration with a `data_schema`

## Document input

Set `file_input` to a file ID (`dfl-...`) or a
completed parse job ID (`pjb-...`).

The job runs asynchronously. Poll `GET /extract/{job_id}` or
register a webhook to monitor completion.

## Query parameters

- `project_id` string, uuid, nullable
- `organization_id` string, uuid, nullable

## Cookies

- `session` string, nullable

## Request body

- ExtractV2JobCreate — Request to create an extraction job. Provide configuration_id or inline configuration.
  - `webhook_configurations` WebhookConfiguration[], nullable — Outbound webhook endpoints to notify on job status changes
    - `webhook_url` string, nullable — URL to receive webhook POST notifications
    - `webhook_headers` object, nullable — Custom HTTP headers sent with each webhook request (e.g. auth tokens)
    - `webhook_events` string[], nullable — Events to subscribe to (e.g. 'parse.success', 'extract.error'). If null, all events are delivered.
    - `webhook_output_format` string, nullable — Response format sent to the webhook: 'string' (default) or 'json'
  - `configuration_id` string, nullable — Saved configuration ID
  - `configuration` ExtractConfiguration — Extract configuration combining parse and extract settings.
    - `target_pages` string, nullable — Comma-separated page numbers or ranges to process (1-based). Omit to process all pages.
    - `max_pages` integer, nullable — Maximum number of pages to process. Omit for no limit.
    - `tier` 'cost_effective' | 'agentic' — Extract tier: cost_effective (5 credits/page) or agentic (15 credits/page)
    - `version` string — Use 'latest' for the latest release for the selected tier or a date string (YYYY-MM-DD format) to pin to the nearest release at or before that date.
    - `data_schema` object, required — JSON Schema defining the fields to extract. Validate with the /schema/validate endpoint first.
    - `extraction_target` 'per_doc' | 'per_page' | 'per_table_row' — Granularity of extraction: per_doc returns one object per document, per_page returns one object per page, per_table_row returns one object per table row
    - `system_prompt` string, nullable — Custom system prompt to guide extraction behavior
    - `cite_sources` boolean — Include citations in results
    - `confidence_scores` boolean — Include confidence scores in results
    - `parse_tier` string, nullable — Parse tier to use before extraction. Defaults to the extract tier if not specified.
    - `parse_config_id` string, nullable — Saved parse configuration ID to control how the document is parsed before extraction
  - `file_input` string, required — File ID or parse job ID to extract from

## Response `200`

Successful Response

- ExtractV2Job — An extraction job.
  - `file_input` string, required — File ID or parse job ID that was extracted
  - `id` string, required — Unique job identifier (job_id)
  - `project_id` string, required — Project this job belongs to
  - `configuration_id` string, nullable — Saved extract configuration ID used for this job, if any
  - `configuration` ExtractConfiguration — Extract configuration combining parse and extract settings.
    - `target_pages` string, nullable — Comma-separated page numbers or ranges to process (1-based). Omit to process all pages.
    - `max_pages` integer, nullable — Maximum number of pages to process. Omit for no limit.
    - `tier` 'cost_effective' | 'agentic' — Extract tier: cost_effective (5 credits/page) or agentic (15 credits/page)
    - `version` string — Use 'latest' for the latest release for the selected tier or a date string (YYYY-MM-DD format) to pin to the nearest release at or before that date.
    - `data_schema` object, required — JSON Schema defining the fields to extract. Validate with the /schema/validate endpoint first.
    - `extraction_target` 'per_doc' | 'per_page' | 'per_table_row' — Granularity of extraction: per_doc returns one object per document, per_page returns one object per page, per_table_row returns one object per table row
    - `system_prompt` string, nullable — Custom system prompt to guide extraction behavior
    - `cite_sources` boolean — Include citations in results
    - `confidence_scores` boolean — Include confidence scores in results
    - `parse_tier` string, nullable — Parse tier to use before extraction. Defaults to the extract tier if not specified.
    - `parse_config_id` string, nullable — Saved parse configuration ID to control how the document is parsed before extraction
  - `status` string, required — Current job status. - `PENDING` — queued, not yet started - `RUNNING` — actively processing - `COMPLETED` — finished successfully - `FAILED` — terminated with an error - `CANCELLED` — cancelled by user
  - `error_message` string, nullable — Error details when status is FAILED
  - `extract_result` union — Extracted data conforming to the data_schema. Returns a single object for per_doc, or an array for per_page / per_table_row.
    - object
    - object[]
  - `extract_metadata` ExtractJobMetadata — Extraction metadata.
    - `field_metadata` ExtractedFieldMetadata — Metadata for extracted fields including document, page, and row level info.
      - `document_metadata` object, nullable — Per-field metadata keyed by field name from your schema. Scalar fields (e.g. `vendor`) map to a FieldMetadataEntry with citation and confidence. Array fields (e.g. `items`) map to a list where each element contains per-sub-field FieldMetadataEntry objects, indexed by array position. Nested objects contain sub-field entries recursively.
      - `page_metadata` object[], nullable — Per-page metadata when extraction_target is per_page
      - `row_metadata` object[], nullable — Per-row metadata when extraction_target is per_table_row
    - `parse_job_id` string, nullable — Reference to the ParseJob ID used for parsing
    - `parse_tier` string, nullable — Parse tier used for parsing the document
  - `metadata` ExtractV2JobMetadata — Job-level metadata.
    - `usage` ExtractJobUsage — Extraction usage metrics.
      - `num_pages_extracted` integer, nullable — Number of pages extracted
  - `created_at` string, date-time, required — Creation timestamp
  - `updated_at` string, date-time, required — Last update timestamp

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/run-llama/apis/llama-platform.md) · [All operations](https://skmtc.net/run-llama/apis/llama-platform/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/run-llama/llama-platform/versions/b17341164de9/schema)