;
};
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 = A, 2 = B, 3 = C)
* `top`: Row number (1-indexed)
* `page`: Sheet index (1 = first sheet)
A citation with `{"left": 3, "top": 15, "page": 2}` points to cell C15 on the second sheet.
## 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:** Values that were inferred (not directly found) may have empty citations. Always check `if field.citations:` before accessing.
## 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