Bounding Boxes

Overview

When extracting content with layout information, Pulse API returns bounding box coordinates for text, tables, and images. This spatial data enables precise document understanding and region-based extraction.

Bounding Box Format

Bounding boxes are returned as normalized coordinates (0-1 range) in an 8-point format:

[x1, y1, x2, y2, x3, y3, x4, y4]

Where:

(x1, y1) = Top-left corner
(x2, y2) = Top-right corner
(x3, y3) = Bottom-right corner
(x4, y4) = Bottom-left corner

Coordinates are normalized to 0-1 range, making them resolution-independent. To convert to pixels, multiply by the page width/height.

Response Structure

The bounding_boxes object groups every detected layout element by its public category. Categories with no detected elements may be omitted.

{
  "bounding_boxes": {
    "Title": [{"id": "txt-1", "original_content": "Statement"}],
    "Header": [],
    "Text": [],
    "List Items": [],
    "Footer": [],
    "caption": [],
    "Page Number": [],
    "Formulas": [],
    "Tables": [{"table_info": {}, "cell_data": []}],
    "Images": [],
    "Words": [],
    "SelectionMarks": [],
    "markdown_with_ids": "..."
  }
}

Every detected layout element is routed into a public grouped category; list items, captions, footers, page numbers, formulas, and selection marks are not discarded. Clients do not need to parse provider-specific category names.

Markdown Fields

Field	Location	Description
`markdown`	Top-level response	Clean markdown content without any ID attributes
`markdown_with_ids`	Inside `bounding_boxes`	Markdown with `data-bb-*` ID attributes that link text to bounding box elements

Use bounding_boxes.markdown_with_ids when you need to correlate text positions with bounding boxes. Use the top-level markdown for clean content display or export. In markdown_with_ids, each text element is wrapped in <div data-bb-text-id="txt-N">, tables carry data-bb-table-id, table cells carry data-bb-cell-id, and visuals carry data-bb-image-id.

Example Response

Here’s a real example of the bounding_boxes object from a workbook with an embedded chart, with figure_processing.show_images: true:

{
  "Images": [
    {
      "id": "excel_image_1_1",
      "visual_type": "chart",
      "page_number": 1,
      "bounding_box": [],
      "image_url": "https://api.runpulse.com/results/13e3e75f-a89a-4d33-a391-e1a17127ab38/images/excel_image_1_1.png",
      "sheet_name": "Charts",
      "excel_range": "D2",
      "chart_type": "BarChart",
      "chart_title": "Revenue",
      "source_ranges": ["'Charts'!$A$2:$A$5", "'Charts'!$B$2:$B$5"],
      "description": "Bar chart showing revenue by quarter."
    }
  ],
  "Tables": [],
  "Text": [
    {
      "id": "txt-2",
      "content": "0a-NCRI",
      "original_content": "NCRI",
      "bounding_box": [0.0267, 0.0872, 0.0689, 0.0789, 0.0743, 0.0908, 0.0321, 0.0996],
      "page_number": 1,
      "confidence": 0.94,
      "reading_order": 1
    }
  ],
  "Title": [
    {
      "id": "txt-1",
      "content": "0a-Doctor Prescription",
      "original_content": "Doctor Prescription",
      "bounding_box": [0.2196, 0.1225, 0.4578, 0.1348, 0.4557, 0.1537, 0.2174, 0.1417],
      "page_number": 1,
      "confidence": 0.99,
      "reading_order": 0
    }
  ]
}

Field Descriptions

All page_number and location.page values are 1-indexed original document page numbers. This holds even when the request used a pages= subset: extracting pages="10-20" produces items labeled pages 10 through 20 across text items, tables, Words, and extension output.

Every element carries confidence — the extractor’s confidence (0-1) that the element was read correctly, or null when it could not score the element — and reading_order, its position in the document-wide reading order (see Reading Order). Responses from model: pulse-ultra-1 carry average_word_confidence (mean word confidence) instead, and no reading_order.

Text Array

Each text element contains:

id: Unique identifier (e.g., txt-1) that links to markdown_with_ids via data-bb-text-id
content: The extracted text with prefix (e.g., 0a-NCRI)
original_content: The clean extracted text without prefix
bounding_box: 8-point coordinate array (may be null for some document types)
page_number: Page where the text appears
confidence: the extractor’s confidence that the element was read correctly (0-1), or null when it could not score the element
reading_order: document-wide reading-order index, shared across categories
selected: Selection state when detect_selections was enabled and the item represents a detected form control or marked-choice region

Title Array

Each title element contains:

id: Unique identifier linking to markdown
content: The title text with prefix
original_content: The clean title text
bounding_box: 8-point coordinate array
page_number: Page where the title appears
confidence: the extractor’s confidence that the element was read correctly (0-1), or null when it could not score the element
reading_order: document-wide reading-order index, shared across categories

Header Array

Each header element contains:

id: Unique identifier linking to markdown
content: The header text with prefix
original_content: The clean header text
bounding_box: 8-point coordinate array
page_number: Page where the header appears
confidence: the extractor’s confidence that the element was read correctly (0-1), or null when it could not score the element
reading_order: document-wide reading-order index, shared across categories

Each footer element contains:

id: Unique identifier linking to markdown
content: The footer text with prefix
original_content: The clean footer text
bounding_box: 8-point coordinate array
page_number: Page where the footer appears
confidence: the extractor’s confidence that the element was read correctly (0-1), or null when it could not score the element
reading_order: document-wide reading-order index, shared across categories

Images Array

Each image element represents a detected chart or embedded image. For PDFs and image inputs, entries are populated when figure detection runs. For spreadsheets, entries are populated for embedded charts and images directly read from the workbook.

Field	When populated	Description
`id`	always	Stable visual identifier (e.g. `excel_image_1_1`, `fig-3`). Joins to the `data-bb-image-id` attribute in `markdown_with_ids`.
`visual_type`	always	`"chart"` (data visualization) or `"image"` (non-chart embedded/detected visual).
`page_number`	always	1-indexed page or sheet number.
`reading_order`	PDFs/images	Document-wide reading-order index shared with the text and table arrays.
`confidence`	PDFs/images	Visuals are not scored: `"N/A"` on the default profile, `null` on `model: pulse-ultra-2`.
`bounding_box`	PDFs/images	8-point coordinate polygon. Empty array for spreadsheets — use `excel_range` instead.
`image_url`	when `figure_processing.show_images: true`	Pulse-hosted URL for the visual image bytes. Fetch via `results.getImage` or any HTTP client with your API key.
`description`	when `figure_processing.description: true`	LLM-generated 1–2 sentence caption.
`content`	usually for spreadsheets	Short caption (e.g. `Chart: Revenue`).
`sheet_name`	spreadsheets	Workbook sheet the visual lives on.
`sheet_index`	spreadsheets	Parsed sheet index after hidden-sheet filtering.
`workbook_sheet_index`	spreadsheets	Original workbook sheet index.
`excel_range`	spreadsheets	Anchor cell or covered cell range (e.g. `D2:K18`).
`chart_type`	spreadsheet charts	Chart class name (e.g. `BarChart`, `LineChart`, `PieChart`).
`chart_title`	spreadsheet charts	Detected chart title text.
`source_ranges`	spreadsheet charts	Cell ranges feeding the chart (e.g. `["Charts!$B$1:$B$3"]`).
`classification`	optional	`{confidence, model, error}` when classification ran.
`render_error`	optional	Non-fatal rendering error for spreadsheet visuals. When set, the entry is still returned but `image_url` may be omitted.
`description_error`	optional	Non-fatal description-generation error.

Fetching Visual Image Bytes

When you set figure_processing.show_images: true on /extract, every chart/image entry comes back with an image_url pointing at GET /results/{jobId}/images/{filename}. Fetch it with your API key to get the raw PNG/JPEG bytes:

import re
from pulse import Pulse
from pulse.types import ExtractRequestFigureProcessing

client = Pulse(api_key="YOUR_API_KEY")
response = client.extract(
    file=open("financials.xlsx", "rb"),
    figure_processing=ExtractRequestFigureProcessing(show_images=True),
)

for img in response.bounding_boxes.images or []:
    m = re.search(r"/results/([^/]+)/images/([^/?#]+)", img.image_url)
    job_id, filename = m.group(1), m.group(2)
    chunks = list(client.results.get_image(job_id=job_id, filename=filename))
    with open(filename, "wb") as f:
        f.write(b"".join(chunks))

import { PulseClient } from "pulse-ts-sdk";
const client = new PulseClient({ apiKey: "YOUR_API_KEY" });

const response = await client.extract({
    file: fs.createReadStream("financials.xlsx"),
    figureProcessing: { showImages: true },
});

for (const img of response.boundingBoxes?.Images ?? []) {
    const m = img.imageUrl?.match(/\/results\/([^/]+)\/images\/([^/?#]+)/);
    if (!m) continue;
    const [, jobId, filename] = m;
    const image = await client.results.getImage({ jobId, filename });
    // Persist `image` per your runtime.
}

See Get Result Image for the full auth contract — visual image fetches always require same-org x-api-key authentication; there is no anonymous access.

Tables Array

The extraction engine decides which table regions exist. Pulse then runs CPU-only cell geometry detection inside those exact table crops. It never creates extra tables from regions the extraction engine did not identify. Each Tables[] entry contains:

Field	Type	Description
`table_info.id`	string	Stable table ID such as `tbl-1`.
`table_info.dimensions.rows`	integer	Occupied grid rows after applying row spans.
`table_info.dimensions.columns`	integer	Occupied grid columns after applying column spans.
`table_info.location.coordinates`	number[]	Normalized 8-number table polygon.
`table_info.location.page`	integer	1-indexed page number.
`table_info.confidence`	number or null	The extractor’s confidence in the table as a whole (0-1).
`table_info.reading_order`	integer	Document-wide reading-order index shared with the text arrays.
`cell_data`	object[]	Every cell authored by the extracted table structure, including empty cells.
`confidence`	number or null	Same value as `table_info.confidence`.

Each cell_data[] item contains:

Field	Type	Description
`id`	string	Stable cell ID such as `tbl-1-r0c0`; it also appears as `data-bb-cell-id` in `markdown_with_ids`.
`position.row`	integer	Zero-indexed starting row.
`position.column`	integer	Zero-indexed starting column after occupied span slots are accounted for.
`text`	string	Indexed cell text. Empty cells remain present with an empty string.
`location.coordinates`	number[]	Normalized cell polygon from crop detection, or a deterministic span-aware grid fallback.
`location.page`	integer	1-indexed page number.
`confidence`	number or null	The cell’s own score (0-1); a cell the extractor could not score carries the table’s value.
`properties.type`	string	`header` for header cells; omitted for data cells.
`properties.spans_rows`	integer	Present only when the cell spans more than one row.
`properties.spans_columns`	integer	Present only when the cell spans more than one column.

{
  "table_info": {
    "id": "tbl-1",
    "dimensions": {"rows": 3, "columns": 2},
    "location": {
      "coordinates": [0.1, 0.3, 0.9, 0.3, 0.9, 0.6, 0.1, 0.6],
      "page": 1
    },
    "confidence": 0.96,
    "reading_order": 4
  },
  "confidence": 0.96,
  "cell_data": [
    {
      "id": "tbl-1-r0c0",
      "position": {"row": 0, "column": 0},
      "text": "0t-Account",
      "location": {
        "coordinates": [0.1, 0.3, 0.5, 0.3, 0.5, 0.4, 0.1, 0.4],
        "page": 1
      },
      "confidence": 0.97,
      "properties": {"type": "header", "spans_columns": 2}
    }
  ]
}

Words Array

Words[] is the standard word geometry collection used to preserve the extraction response contract. Each item contains content, page_number, confidence, and a polygon represented as [{"x": number, "y": number}, ...].

{
  "content": "Account",
  "page_number": 1,
  "bounding_box": [
    {"x": 0.1, "y": 0.3},
    {"x": 0.2, "y": 0.3},
    {"x": 0.2, "y": 0.34},
    {"x": 0.1, "y": 0.34}
  ],
  "confidence": 0.99
}

Selection Marks Array

When selection detection finds marked controls, SelectionMarks[] contains page_number, state (selected or unselected), confidence, and a normalized polygon.

Page Number Array

Each page number element contains:

id: Unique identifier
content: The page number text
original_content: The clean page number text
bounding_box: 8-point coordinate array
page_number: Page where it appears
confidence: the extractor’s confidence that the element was read correctly (0-1), or null when it could not score the element
reading_order: document-wide reading-order index, shared across categories

The id field allows you to link bounding box elements to specific locations in the markdown_with_ids field via data-bb-text-id attributes.

Reading Order

Grouping elements by category loses the order the page was read in. Every element carries reading_order, the extractor’s document-wide index: sort the union of Text, Title, Header, Footer, List Items, caption, Page Number, Formulas, Tables (table_info.reading_order) and Images by it to rebuild the document flow. Requests with model: pulse-ultra-2 also return the flow directly as bounding_boxes.ordered_elements, one entry per element in reading order:

Field	Description
`order`	Position in the document flow (the element’s `reading_order`).
`id`	Element id, joining to its entry in the category array (`txt-3`, `tbl-1`, `fig-2`).
`type`	Category array the element lives in (`Text`, `Title`, `Tables`, `Images`, …).
`source_category`	The extractor’s own label before category mapping.
`page_number`	1-indexed page.
`bounding_box`	8-point coordinate array.
`content`	Element text (text items only).
`confidence`	Same score the element carries in its category array.
`selected`	Selection marks only: `true` or `false`.

ordered_elements is not returned on the default profile; use reading_order there.

Footnote References

When you enable extensions.footnote_references in your extract request, the response includes an extensions.footnoteReferences array that links each footnote to the body text that cites it, using bounding box IDs and coordinates. Each entry contains:

symbol — the footnote marker as written in the footnote text (e.g. *, †, ⁴, (1))
footnoteTextId, footnotePageNumber, footnoteText — where the footnote text lives and what it says
referenceTextIds — id values from the Text, Title, or Header arrays for body blocks that contain the marker
references — one entry per located marker occurrence, with the citing block (or table cell), its page, and the marker’s own bounding box when it could be pinned

{
  "extensions": {
    "footnoteReferences": [
      {
        "symbol": "*",
        "footnoteTextId": "txt-42",
        "footnotePageNumber": 1,
        "footnoteText": "Equal contribution. Listing order is random.",
        "referenceTextIds": ["txt-5", "txt-12"],
        "references": [
          {
            "textId": "txt-5",
            "pageNumber": 1,
            "markerBoundingBox": [0.312, 0.221, 0.319, 0.221, 0.319, 0.231, 0.312, 0.231],
            "source": "native"
          },
          {
            "textId": "txt-12",
            "pageNumber": 1,
            "markerBoundingBox": null,
            "source": "text"
          }
        ]
      }
    ]
  }
}

Use footnoteTextId to look up the footnote’s position in bounding_boxes.Footer (or bounding_boxes.Text), and each references[] entry to highlight the exact marker: markerBoundingBox is in the same normalized coordinates as every other bounding_box, so it can be drawn directly on the page. Several footnotes can share one footnoteTextId when the extractor returned them as a single block; symbol plus footnoteTextId is the unique key.

Footnote references are available for PDFs and images. Text-based PDFs give the most precise marker positions. See the Extract endpoint for the full field reference and usage examples.

Converting Coordinates

To convert normalized coordinates to pixel coordinates:

def normalize_to_pixels(bbox, page_width, page_height):
    """Convert normalized bounding box to pixel coordinates."""
    return [
        bbox[0] * page_width,   # x1
        bbox[1] * page_height,  # y1
        bbox[2] * page_width,   # x2
        bbox[3] * page_height,  # y2
        bbox[4] * page_width,   # x3
        bbox[5] * page_height,  # y3
        bbox[6] * page_width,   # x4
        bbox[7] * page_height   # y4
    ]

# Example: Convert for a standard letter-size page at 72 DPI
page_width = 612  # 8.5 inches * 72 DPI
page_height = 792  # 11 inches * 72 DPI

normalized_bbox = [0.1, 0.1, 0.3, 0.1, 0.3, 0.15, 0.1, 0.15]
pixel_bbox = normalize_to_pixels(normalized_bbox, page_width, page_height)

API Reference

Pipeline Steps

Batch & Pipelines

Forms

Jobs, Results & Webhooks

Account & Usage

Overview

Bounding Box Format

Response Structure

Markdown Fields

Example Response

Field Descriptions

Text Array

Title Array

Header Array

Footer Array

Images Array

Fetching Visual Image Bytes

Tables Array

Words Array

Selection Marks Array

Page Number Array

Reading Order

Footnote References

Converting Coordinates

Next Steps

Extract Endpoint

Structured Output

​Overview

​Bounding Box Format

​Response Structure

​Markdown Fields

​Example Response

​Field Descriptions

​Text Array

​Title Array

​Header Array

​Footer Array

​Images Array

​Fetching Visual Image Bytes

​Tables Array

​Words Array

​Selection Marks Array

​Page Number Array

​Reading Order

​Footnote References

​Converting Coordinates

​Next Steps

Extract Endpoint

Structured Output

Overview

Bounding Box Format

Response Structure

Markdown Fields

Example Response

Field Descriptions

Text Array

Title Array

Header Array

Footer Array

Images Array

Fetching Visual Image Bytes

Tables Array

Words Array

Selection Marks Array

Page Number Array

Reading Order

Footnote References

Converting Coordinates

Next Steps