;
};
Citations tell you exactly where each extracted value came from in the document. When enabled, every field includes bounding box coordinates pointing to the source text.
This matters for:
* **Verification**: Confirm extractions are correct by checking source text
* **Compliance**: Maintain audit trails for regulated workflows
* **Debugging**: See where the model looked when values are wrong
* **User experience**: Let users click from extracted data to the original location
```python theme={null}
result = client.extract.run(
input=upload,
instructions={"schema": schema},
settings={
"citations": {"enabled": True}
}
)
```
## Response Structure
With citations enabled, each value becomes an object with `value` and `citations`:
```json theme={null}
{
"result": {
"invoice_total": {
"value": 1575.00,
"citations": [
{
"type": "Table",
"content": "Total Due: $1,575.00",
"bbox": {
"left": 0.65,
"top": 0.82,
"width": 0.25,
"height": 0.03,
"page": 1,
"original_page": 1
},
"confidence": "high",
"granular_confidence": {
"extract_confidence": 0.95,
"parse_confidence": 0.91
},
"parentBlock": {
"type": "Table",
"content": "Subtotal: $1,500.00\nTax: $75.00\nTotal Due: $1,575.00",
"bbox": {"left": 0.60, "top": 0.75, "width": 0.35, "height": 0.12, "page": 1}
}
}
]
}
}
}
```
**Fields:**
* `type`: Block type (`Text`, `Table`, `Key Value`, etc.)
* `content`: The source text
* `bbox`: Bounding box coordinates (normalized 0-1 for PDFs/images)
* `confidence`: `"high"` or `"low"`
* `granular_confidence`: Numeric scores (`extract_confidence`, `parse_confidence`) between 0-1
* `parentBlock`: The larger Parse block containing this citation, for context
## Working with Citations
**Accessing a scalar field:**
```python theme={null}
invoice_number = result.result["invoice_number"]
print(f"Value: {invoice_number.value}")
if invoice_number.citations:
citation = invoice_number.citations[0]
print(f"Found on page {citation.bbox.page}")
print(f"Source text: {citation.content}")
```
**Looping through array items:**
```python theme={null}
for item in result.result["line_items"]:
amount = item["amount"]
print(f"${amount.value}")
if amount.citations:
print(f" Found on page {amount.citations[0].bbox.page}")
```
## Bounding Box Coordinates
For PDFs and images, coordinates are normalized to \[0, 1] relative to page dimensions. `left: 0.5` means halfway across the page.
`page` is the page number in the processed result. `original_page` is the page number in the original document, which differs when you use page ranges.
To convert to pixels, multiply by page dimensions:
```python theme={null}
x_px = bbox["left"] * page_width_px
y_px = bbox["top"] * page_height_px
```
## Spreadsheet Citations
Excel and CSV files use cell coordinates instead of normalized positions:
* `left`: Column number (1-indexed, so 1 = A, 2 = B, 3 = C)
* `top`: Row number (1-indexed, so 1 = first row)
* `page`: Sheet number (1-indexed position of the sheet in the workbook)
A citation with `{"left": 3, "top": 15, "page": 2}` points to cell C15 on the second sheet.
All extraction modes use this convention, including `spreadsheet_agent` and `deep_extract`.
## Confidence Scores
Each citation includes a `confidence` field with a categorical value (`"high"` or `"low"`).
By default in v3, `numerical_confidence` is **enabled**, which adds `granular_confidence` with numeric 0-1 scores:
```json theme={null}
{
"confidence": "high",
"granular_confidence": {
"extract_confidence": 0.95,
"parse_confidence": 0.91
}
}
```
* `extract_confidence`: How confident the LLM is about the extraction
* `parse_confidence`: How confident the OCR/parsing is about the underlying text
To disable numeric scores and only get categorical confidence:
```python theme={null}
settings={
"citations": {
"enabled": True,
"numerical_confidence": False # Only return "high"/"low"
}
}
```
Low `parse_confidence` suggests OCR errors. Low `extract_confidence` suggests the model was uncertain about interpretation.
## Constraints
**Citations disable chunking:** The document is processed as a single unit to maintain precise coordinate mapping.
**Empty citations:** A field's `citations` array can be empty in two cases. The value was inferred rather than found directly in the document, or the value was found but Reducto could not reliably localize it to a source span. The second case is rare. In both cases the `value` is still returned correctly. Always check `if field.citations:` before accessing them. For an inferred value, re-running will not add a citation, so adjust the schema or field description if you need the value tied to source text. For the rare localization failure, re-running the extraction can recover the citation.
## Studio Visualization
Every response includes a `studio_link`. In Studio, citations are interactive:
* Click an extracted field to highlight its source in the document
* Click a highlight to jump to the corresponding field