Create Extract Job

ExtractV2Job extract().create(, )

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.

ParametersExpand Collapse

ExtractCreateParams params

Optional<String> organizationId

Optional<String> projectId

ExtractV2JobCreate extractV2JobCreate

Request to create an extraction job. Provide configuration_id or inline configuration.

ReturnsExpand Collapse

class ExtractV2Job:

An extraction job.

String id

Unique job identifier (job_id)

LocalDateTime createdAt

Creation timestamp

formatdate-time

String fileInput

File ID or parse job ID that was extracted

String projectId

Project this job belongs to

String status

Current job status.

PENDING — queued, not yet started
RUNNING — actively processing
COMPLETED — finished successfully
FAILED — terminated with an error
CANCELLED — cancelled by user

LocalDateTime updatedAt

Last update timestamp

formatdate-time

Optional<ExtractConfiguration> configuration

Extract configuration combining parse and extract settings.

DataSchema dataSchema

JSON Schema defining the fields to extract. Validate with the /schema/validate endpoint first.

One of the following:

class UnionMember0:

List<JsonValue>

String

double

boolean

Optional<Boolean> citeSources

Include citations in results

Optional<Boolean> confidenceScores

Include confidence scores in results

Optional<ExtractionTarget> extractionTarget

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

One of the following:

PER_DOC("per_doc")

PER_PAGE("per_page")

PER_TABLE_ROW("per_table_row")

Optional<Long> maxPages

Maximum number of pages to process. Omit for no limit.

minimum1

Optional<String> parseConfigId

Saved parse configuration ID to control how the document is parsed before extraction

Optional<String> parseTier

Parse tier to use before extraction. Defaults to the extract tier if not specified.

Optional<String> systemPrompt

Custom system prompt to guide extraction behavior

Optional<String> targetPages

Comma-separated page numbers or ranges to process (1-based). Omit to process all pages.

Optional<Tier> tier

Extract tier: cost_effective (5 credits/page) or agentic (15 credits/page)

One of the following:

COST_EFFECTIVE("cost_effective")

AGENTIC("agentic")

Optional<String> version

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.

Optional<String> configurationId

Saved extract configuration ID used for this job, if any

Optional<String> errorMessage

Error details when status is FAILED

Optional<ExtractJobMetadata> extractMetadata

Extraction metadata.

Optional<ExtractedFieldMetadata> fieldMetadata

Metadata for extracted fields including document, page, and row level info.

Optional<DocumentMetadata> documentMetadata

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.

One of the following:

class UnionMember0:

List<JsonValue>

String

double

boolean

Optional<List<PageMetadata>> pageMetadata

Per-page metadata when extraction_target is per_page

One of the following:

class UnionMember0:

List<JsonValue>

String

double

boolean

Optional<List<RowMetadata>> rowMetadata

Per-row metadata when extraction_target is per_table_row

One of the following:

class UnionMember0:

List<JsonValue>

String

double

boolean

Optional<String> parseJobId

Reference to the ParseJob ID used for parsing

Optional<String> parseTier

Parse tier used for parsing the document

Optional<ExtractResult> extractResult

Extracted data conforming to the data_schema. Returns a single object for per_doc, or an array for per_page / per_table_row.

One of the following:

class UnionMember0:

class InnerUnionMember0:

List<JsonValue>

String

double

boolean

List<UnnamedSchemaWithArrayParent0>

One of the following:

class UnionMember0:

List<JsonValue>

String

double

boolean

Optional<Metadata> metadata

Job-level metadata.

Optional<ExtractJobUsage> usage

Extraction usage metrics.

Optional<Long> numPagesExtracted

Number of pages extracted

Create Extract Job

package com.llamacloud_prod.api.example;

import com.llamacloud_prod.api.client.LlamaCloudClient;
import com.llamacloud_prod.api.client.okhttp.LlamaCloudOkHttpClient;
import com.llamacloud_prod.api.models.extract.ExtractCreateParams;
import com.llamacloud_prod.api.models.extract.ExtractV2Job;
import com.llamacloud_prod.api.models.extract.ExtractV2JobCreate;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();

        ExtractV2JobCreate params = ExtractV2JobCreate.builder()
            .fileInput("dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")
            .build();
        ExtractV2Job extractV2Job = client.extract().create(params);
    }
}

{
  "id": "ext-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "created_at": "2019-12-27T18:11:19.117Z",
  "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "project_id": "prj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "COMPLETED",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "configuration": {
    "data_schema": {
      "foo": {
        "foo": "bar"
      }
    },
    "cite_sources": true,
    "confidence_scores": true,
    "extraction_target": "per_doc",
    "max_pages": 10,
    "parse_config_id": "cfg-11111111-2222-3333-4444-555555555555",
    "parse_tier": "fast",
    "system_prompt": "Extract all monetary values in USD. If a currency is not specified, assume USD.",
    "target_pages": "1,3,5-7",
    "tier": "cost_effective",
    "version": "latest"
  },
  "configuration_id": "cfg-11111111-2222-3333-4444-555555555555",
  "error_message": "error_message",
  "extract_metadata": {
    "field_metadata": {
      "document_metadata": {
        "items": [
          {
            "amount": {
              "citation": [
                {
                  "matching_text": "$10.00",
                  "page": 1
                }
              ],
              "confidence": 1
            },
            "description": {
              "citation": [
                {
                  "matching_text": "$10/month",
                  "page": 1
                }
              ],
              "confidence": 0.998
            }
          }
        ],
        "total": {
          "citation": "bar",
          "confidence": "bar"
        },
        "vendor": {
          "citation": "bar",
          "confidence": "bar",
          "extraction_confidence": "bar",
          "parsing_confidence": "bar"
        }
      },
      "page_metadata": [
        {
          "foo": {
            "foo": "bar"
          }
        }
      ],
      "row_metadata": [
        {
          "foo": {
            "foo": "bar"
          }
        }
      ]
    },
    "parse_job_id": "parse_job_id",
    "parse_tier": "parse_tier"
  },
  "extract_result": {
    "foo": {
      "foo": "bar"
    }
  },
  "metadata": {
    "usage": {
      "num_pages_extracted": 0
    }
  }
}

Returns Examples

{
  "id": "ext-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "created_at": "2019-12-27T18:11:19.117Z",
  "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "project_id": "prj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "COMPLETED",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "configuration": {
    "data_schema": {
      "foo": {
        "foo": "bar"
      }
    },
    "cite_sources": true,
    "confidence_scores": true,
    "extraction_target": "per_doc",
    "max_pages": 10,
    "parse_config_id": "cfg-11111111-2222-3333-4444-555555555555",
    "parse_tier": "fast",
    "system_prompt": "Extract all monetary values in USD. If a currency is not specified, assume USD.",
    "target_pages": "1,3,5-7",
    "tier": "cost_effective",
    "version": "latest"
  },
  "configuration_id": "cfg-11111111-2222-3333-4444-555555555555",
  "error_message": "error_message",
  "extract_metadata": {
    "field_metadata": {
      "document_metadata": {
        "items": [
          {
            "amount": {
              "citation": [
                {
                  "matching_text": "$10.00",
                  "page": 1
                }
              ],
              "confidence": 1
            },
            "description": {
              "citation": [
                {
                  "matching_text": "$10/month",
                  "page": 1
                }
              ],
              "confidence": 0.998
            }
          }
        ],
        "total": {
          "citation": "bar",
          "confidence": "bar"
        },
        "vendor": {
          "citation": "bar",
          "confidence": "bar",
          "extraction_confidence": "bar",
          "parsing_confidence": "bar"
        }
      },
      "page_metadata": [
        {
          "foo": {
            "foo": "bar"
          }
        }
      ],
      "row_metadata": [
        {
          "foo": {
            "foo": "bar"
          }
        }
      ]
    },
    "parse_job_id": "parse_job_id",
    "parse_tier": "parse_tier"
  },
  "extract_result": {
    "foo": {
      "foo": "bar"
    }
  },
  "metadata": {
    "usage": {
      "num_pages_extracted": 0
    }
  }
}