Extract data from spreadsheets

The Data Extraction API reads XLSX workbooks from their cells, and each visible worksheet becomes one page. The cells on it come back as the tables, headings, and paragraphs a person sees in the sheet. The output uses the same element types and the same Markdown as a PDF, so one pipeline handles both. No optical character recognition (OCR) runs on XLSX workbooks.

Supported formats

The API reads XLSX workbooks cell by cell. Other spreadsheet formats listed in the supported file types guide are still accepted, but they don’t use this optimized XLSX path.

Send a workbook

Send a workbook to the parse endpoint the same way as any other file.

curl --fail-with-body -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer your_api_key_goes_here" \
  -F "file=@q3-report.xlsx" \
  -F 'instructions={"output":{"format":"markdown"}}'

import requests

response = requests.post(
    "https://api.nutrient.io/extraction/parse",
    headers={"Authorization": "Bearer your_api_key_goes_here"},
    files={"file": open("q3-report.xlsx", "rb")},
    data={"instructions": '{"output":{"format":"markdown"}}'},
)

result = response.json()
if result["status"] != 200:
    raise RuntimeError(result["errorMessage"])

print(result["output"]["markdown"])

import fs from "node:fs";

const form = new FormData();
form.append("file", fs.createReadStream("q3-report.xlsx"));
form.append("instructions", JSON.stringify({ output: { format: "markdown" } }));

const response = await fetch("https://api.nutrient.io/extraction/parse", {
  method: "POST",
  headers: { Authorization: "Bearer your_api_key_goes_here" },
  body: form,
});

const result = await response.json();
if (result.status !== 200) {
  throw new Error(result.errorMessage);
}

console.log(result.output.markdown);

For XLSX workbooks, the mode field has no effect on how cells are read. Leave it out, or keep whatever mode your pipeline already sends for other files.

What a sheet becomes

The API starts with the used range. Only the rectangle that holds text counts, so the API ignores empty rows and columns around it.

Inside that range, the API divides the sheet into regions:

• The sheet is cut at completely empty rows and columns.
• Tables declared in Excel stay whole, even when they contain empty rows or columns.
• Narrow blank columns are treated as spacing inside one table.
• Pieces separated by a blank column are joined when they cover the same rows.
• A single header row separated from its data by one blank row stays with the data.

Each region then becomes a document element:

• A merged or bold cell on the first row above a table becomes a level-2 heading.
• One or two values stacked in a single column become paragraphs.
• Three or more values stacked under each other become a one-column table.
• Everything else becomes a table.

The API returns regions top to bottom by their first row, and left to right for ties. It detects header cells from Excel table headers, from text headers above numeric or Boolean rows, or from a single bold first row.

For example, a sheet named Q3 sales has a sentence in A1, a merged bold title in A3:C3, and a table in A4:C7. It returns Markdown like this:

# Q3 sales

All amounts in USD thousands. Figures are unaudited.

## Q3 2026 regional sales

<table>
 <tr><th>Region</th><th>Orders</th><th>Revenue</th></tr>
 <tr><td>North</td><td>412</td><td>1284.5</td></tr>
 <tr><td>South</td><td></td><td>978.0</td></tr>
 <tr><td>East</td><td>388</td><td>1102.3</td></tr>
</table>

Cell values

Spreadsheet output uses the text Excel displays:

• A cell storing 1.25 and formatted to one decimal returns 1.3.
• Dates, percentages, and currency values return with the formatting saved in Excel.
• Formula cells return the last calculated result saved in the file. Formulas aren’t recalculated.
• Booleans return TRUE or FALSE.
• Error values such as #DIV/0! return as text.
• Line breaks inside a cell are kept in JSON output and replaced with spaces inside Markdown tables.
• Empty cells inside a table remain empty, so columns don’t shift.
• Merged cells are returned once, with their row and column span.

Hyperlink targets, images, charts, shapes, comments, cell colors, and fonts aren’t returned.

JSON output

Spatial JSON output returns each visible sheet as one page. Elements carry bounds in the sheet’s own coordinate space, and elements read directly from cells report confidence as 1.0. Table cells carry their row, column, row span, column span, text, bounds, and header status.

Refer to the document elements and coordinate spaces guides for the shared JSON structure.

Limits

• Hidden sheets aren’t converted.
• Cells return the displayed text, not the stored number or the formula.
• Side-by-side tables of exactly the same height are returned as one table.
• One or two values stacked in a single column become paragraphs. Three or more become a one-column table.
• Hyperlinks, images, charts, comments, and formatting aren’t returned.
• Header detection finds at most one header row unless the table is declared in Excel.
• Numeric labels, such as year columns, aren’t recognized as headers.
• A very sparse sheet returns each value as a paragraph instead of a table.

Speed

An internal test in September 2026 processed the same 40 XLSX workbooks on the same machine before and after the cell-based path. XLSX workbook conversion was about 76 times faster end to end. Three workbooks that previously hit a two-minute timeout finished in less than three seconds.

Related guides

• Extract Markdown
• Extract document elements
• Supported file types
• Build a RAG ingestion pipeline