Skip to main content
POST
Reconstruct charts from a saved extraction or split

Overview

Pipeline Step 2 (terminal) — Charts reuses a completed extraction or split. It does not accept a document upload directly.
Reconstruct line, scatter, bar, pie, donut, and well-log charts as auditable data. Each result contains the source page and normalized bounding box, reconstructed series, axis metadata, a confidence score, and warnings. You can also request Excel, CSV, or LAS exports. Set charts_config.document_analysis to true to analyze the selected document pages for charts, tables, image descriptions, and readable lithology text. It uses the same extraction_id or split_id; no new upload is needed. Omit the option or set it to false to keep the default chart reconstruction. For PDFs with vector well-log curves, document analysis can recover separate traces that share a printed scale, including traces drawn as short segments. Numeric recovery requires readable measurement and depth rulers. Ambiguous scales, overlapping traces, or scale changes between pages can leave gaps or prevent recovery. The endpoint can run synchronously or asynchronously and is billed at 1 credit per reconstructed chart. It must be enabled for your organization.

Request

Provide exactly one source:

charts_config

boolean
default:false
Analyze the selected document pages and include tables, descriptions, warnings, coverage, and supported lithology records in the response. Accepts JSON true or false only.
integer
default:20
Requested samples per continuous series, from 2 to 500. With document analysis, this is a target: source curves may retain more points to preserve extrema, step corners, and gaps.
boolean
default:false
When document_analysis is false, inspect difficult regions at higher resolution. This can improve recovery at additional latency.
array
default:["excel"]
Any of excel, csv, and las. Use [] to disable exports. LAS applies only to compatible well logs.
Options belong inside charts_config. Top-level document_analysis, data_points, agentic_zoom, export_formats, generate_las, and layout_confidence are rejected.
For a split, replace extraction_id with split_id and omit page_range.

Response

With async: true, the endpoint returns HTTP 202:
Poll GET /job/{job_id} until the job reaches a terminal status. The completed chart response is returned in the job response’s result field. charts_id belongs to that completed result; it is not duplicated in the initial async acknowledgement. Extraction mode returns a flat charts array. Split mode returns results, keyed by topic, with each topic’s inherited pages and charts. count is the total number of charts across the response. When requested, document_analysis is included alongside the charts and exports. It contains results for the selected pages, including the inherited pages in split mode. Tables, descriptions, and lithology records do not increase count, and may be returned even when no numeric chart can be reconstructed. coverage.status is complete, partial, or failed. A complete status means the scheduled regions were processed; it does not guarantee that every curve was recovered or every value is correct.
excel_url mirrors the first Excel export URL when one is available. Iterate over exports when you request multiple formats. If an export cannot be produced, export_warnings explains why without failing the chart reconstruction.

Lithology records

document_analysis.lithology recovers supported prose from PDFs with readable native text. It does not recover lithology records from scanned images or infer rock proportions from colors, symbols, or chemical curves. An empty array does not establish that the document contains no lithology. Each record preserves the source description, including line breaks. Its depth_top and depth_base come from an explicitly printed interval; unbounded descriptions keep both fields null. depth_unit is m, ft, or an empty string when no unit is available. Paragraph position is not used as a depth bound. page_number identifies the first page; page_numbers lists all source pages for the record. bounding_box is normalized to that first page. For source review, source_evidence.fragments contains each page’s original text, page_number, and bbox. These boxes and interval_bbox use [x0, y0, x1, y1] in PDF points from the displayed page’s top-left corner, rather than normalized coordinates. source_evidence.method is native_printed_interval or native_printed_description. interval_text retains the printed interval; interval_text and interval_bbox are null for unbounded descriptions.

Export Downloads

With document analysis enabled:
  • Excel includes chart data, tables, descriptions, and coverage notes. When lithology records are available, it also includes a Lithology worksheet.
  • CSV exports include chart-data.csv for chart points and, when lithology records are available, a separate lithology.csv. Iterate over exports to download both. Other tables and descriptions are available in Excel and the JSON response.
  • LAS is generated for compatible well-log charts with numeric measurement and depth points. Missing or conflicting curve intervals remain null. Lithology descriptions are not encoded as numeric LAS curves.
The lithology worksheet and CSV include the record ID, pages, top and base depths, unit, description, status, and printed interval. Missing bounds remain blank in these exports; the JSON response retains null and the detailed source evidence. Every export URL:
  • requires the same API key as the chart request;
  • belongs to the organization that created the chart result;
  • is deleted after one successful stream;
  • must not be prefetched by an agent, UI, or link preview.
Store the downloaded file. Do not store the URL as a durable artifact reference.

Retrieve Results

Authenticated applications can hydrate saved views without rerunning reconstruction: The public route intentionally returns 404 for missing, private, expired, and deleted extractions so it does not disclose which condition failed.

Accuracy

Chart values are reconstructed from the source document, including vector geometry or raster images; they are not original instrument readings. Review confidence and warnings, and validate consequential data against the source using the returned page_number and bounding_box. With document analysis, also review document_analysis.warnings and coverage for missing regions. When document analysis is disabled, agentic_zoom can help with small labels or dense curves, but does not guarantee exact source values. Document curve results use confidence: 0 when unscored. This is not a measured accuracy percentage; check the source and warnings before using the values.

Extract

Create the saved extraction consumed by Charts.

Chaining Steps

Reuse extraction and split IDs across downstream steps.

Authorizations

x-api-key
string
header
required

Body

application/json

Input for POST /charts. Provide exactly one existing extraction_id or split_id. Document analysis uses the same source IDs and options.

extraction_id
string<uuid>
required

Completed extraction to process.

split_id
string<uuid>

Completed split whose topic page groups should be processed.

page_range
string

Optional 1-indexed pages for extraction mode, for example "1-3,5". Do not provide this with split_id; split pages are inherited.

Pattern: ^[0-9, -]+$
charts_config
object

Chart reconstruction options. Defaults are used when omitted.

async
boolean
default:false

When true, returns immediately with a job ID. Poll GET /job/{job_id} for the completed chart result.

Response

Completed chart reconstruction.

charts_id
string<uuid>
required
count
integer
required

Total reconstructed charts across the response.

Required range: x >= 0
exports
object[]
required
excel_url
string<uri> | null
required
deprecated

Compatibility alias for the Excel item in exports.

extraction_id
string<uuid> | null
split_id
string<uuid>
page_range
string
charts
object[]

Present in extraction mode.

results
object

Split-mode results keyed by topic name.

export_warnings
string[]
document_analysis
object

Additional result when charts_config.document_analysis is true. Contains only selected-page results alongside the existing charts and exports. Tables and descriptions are also included in the Excel export and do not increase the reconstructed-chart count. Complete scheduled coverage does not certify factual accuracy or recovery of every source curve.

credits_used
number<float>