# Convert XLSX to JSON

> To convert XLSX to JSON, send one POST to /v1/xlsx-to-json with the XLSX source. Each call costs $0.005 in USDC on Base via x402, with no account and no API key. The source file can be up to 25 MB.

- Endpoint: `POST /v1/xlsx-to-json`
- Price: $0.005 per successful call
- API: [xlsx-to-json](https://grist.tools/docs/xlsx-to-json)

## Limits

| Limit | Value |
| --- | --- |
| Largest source file | 25 MB (26,214,400 bytes) |
| Timeout | 40 s |
| Source formats | XLSX |
| Output formats | JSON |
| Option header_row | default 1 |
| Option max_rows | default 1000 |

## Example

A real XLSX to JSON run of xlsx-to-json.

Request body:

```json
{
  "url": "https://grist.tools/samples/documents/garden-inventory.xlsx",
  "header_row": 1,
  "max_rows": 1000
}
```

Response:

```json
{
  "source_url": "https://grist.tools/samples/documents/garden-inventory.xlsx",
  "sheet_count": 2,
  "sheets": [
    {
      "name": "Seeds",
      "columns": [
        "Variety",
        "Crop",
        "Packets",
        "Sown On",
        "Organic"
      ],
      "rows": [
        {
          "Variety": "Early Scarlet",
          "Crop": "Radish",
          "Packets": 4,
          "Sown On": "2026-03-14T00:00:00.000Z",
          "Organic": true
        },
        {
          "Variety": "Green Arrow",
          "Crop": "Pea",
          "Packets": 6,
          "Sown On": "2026-03-21T00:00:00.000Z",
          "Organic": true
        },
        {
          "Variety": "Golden Cherry",
          "Crop": "Tomato",
          "Packets": 2,
          "Sown On": "2026-04-11T00:00:00.000Z",
          "Organic": false
        }
      ],
      "row_count": 3,
      "truncated": false
    },
    {
      "name": "Tools",
      "columns": [
        "Tool",
        "Count",
        "Location"
      ],
      "rows": [
        {
          "Tool": "Spade",
          "Count": 3,
          "Location": "Shed"
        },
        {
          "Tool": "Watering can",
          "Count": 5,
          "Location": "Rain barrels"
        }
      ],
      "row_count": 2,
      "truncated": false
    }
  ]
}
```

Source file: documents/garden-inventory.xlsx, 6.7 KB (6,816 bytes). Two-sheet Excel workbook of garden stock: Seeds (text, counts, sowing dates, a boolean) and Tools, written by exceljs with pinned document and zip dates. The request sets header_row to 1 and max_rows to 1000. The recorded run returned 639 bytes of JSON, 9% of the source size, with 2 sheets.

## Format notes

XLSX as a source: An XLSX workbook is an OOXML ZIP archive, so the first gate only confirms the PK 03 04 signature; exceljs is what establishes that the archive is a workbook and fails otherwise. Before exceljs reads anything, the inflated size and the entry count of the archive are bounded, because the download cap cannot stop a ZIP bomb. The number of worksheets is bounded too, and max_rows is applied to each sheet separately, marking a cut sheet as truncated. The header_row option names the row holding column names, or selects positional arrays instead; blank headings become generated names and duplicates get suffixes. Error cells become null, dates become ISO-8601 strings and formulas contribute their cached results. A sheet name that is not in the workbook is refused with the list of available names.

JSON as a target: The JSON that Grist returns keeps different value types depending on the reader. csv-to-json leaves every cell a string and returns header-keyed objects, or positional arrays when header is false, together with the delimiter, the column list, a row count and a truncated flag. xlsx-to-json keeps numbers and booleans as typed values, turns dates into ISO-8601 strings, uses the cached result of a formula, and reduces rich text and hyperlinks to their text; error cells become null. It returns every worksheet, or a single sheet selected by exact name. A delimited source therefore produces JSON that needs type conversion by the caller, while a workbook source produces typed values straight away. Blank and duplicate headings are made unique by both readers before they become object keys.

## Errors

- `invalid_input` (400)
- `blocked_target` (403)
- `unreachable_target` (424)
- `upstream_timeout` (424)
- `unsupported_content_type` (415)
- `too_large` (413)
- `unprocessable` (422)
- `internal` (500)

When each is raised, and what it means for payment: https://grist.tools/docs/xlsx-to-json.

## Questions

### What does it cost to convert XLSX to JSON?

$0.005 per call, paid in USDC on Base via x402.

### How large can the XLSX file be?

Up to 25 MB (26,214,400 bytes). Past a limit the call answers too_large (413).

### What happens if the conversion fails?

The tool answers with a typed JSON error from the errors table. Payment is settled only after the tool has produced its result; a call that fails inside the tool is never settled.

This page as HTML: https://grist.tools/tools/xlsx-to-json. Every page of grist.tools has a Markdown version at its address plus .md.
