> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getclean.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean.
> Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else.
> The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it.
> The product's name is written getclean, in lower case.

# Get every table, cell by cell

> Ask a record for its tables and get each one as rows of cells, with its merged cells and its header rows. A figure in your report can then name the row and the column it came from.

The figure a credit memo needs is in a table whose top heading spans 3 columns. As plain text that table is a run of numbers, and nothing says which heading a number is under. A record has the table as a table: rows of cells, the cells that are merged, and the rows and the columns that are headings. A record is the copy of a source that getclean stores after a fetch or an upload, and `list_blocks` returns its parts by kind.

## List the tables of a record

Send the id of the record and the kind of block you want.

```bash cURL theme={"theme":"css-variables"}
curl "https://api.getclean.ai/v1/contents/CONTENTS_ID/blocks?block_kinds=table" \
  --header "Authorization: Bearer $GETCLEAN_API_KEY"
```

```python Python theme={"theme":"css-variables"}
from getclean import GetClean

client = GetClean()

tables = client.list_blocks(contents_id="CONTENTS_ID", block_kinds=["table"])
for block in tables:
    print(block.table.rows)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { GetClean } from "getclean";

const client = new GetClean();

const tables = await client.listBlocks("CONTENTS_ID", { block_kinds: ["table"] });
for await (const block of tables) {
    console.log(block.table?.rows);
}
```

Replace `CONTENTS_ID` with the id of a record.

Each block of the response is one table. This response is cut to the table of its one block.

```json 200 OK theme={"theme":"css-variables"}
{
  "blocks": [
    {
      "kind": "table",
      "table": {
        "caption": null,
        "rows": [["Quarter", "Margin"], ["Q3", "41.2%"]],
        "spans": [],
        "header_rows": [0],
        "header_columns": [],
        "basis": "structure"
      }
    }
  ]
}
```

`rows` has the cells as the source displays them. Every row has every column, and an empty cell is an empty string. `header_rows` and `header_columns` name the headings by their position, counted from 0.

A block also has its place: its section, and on a document its page. A table that continues over several pages of a document is one block.

## Read a merged cell

A merged cell is where most conversions of a table go wrong, because the cell belongs to several columns or rows at once. `spans` lists each merged cell with the row and the column it starts in and the number of rows and columns it covers. The text of the cell is in every slot it covers. This table has one heading over 2 columns.

```json A table with a merged heading theme={"theme":"css-variables"}
{
  "rows": [
    ["", "2025", "2025"],
    ["Segment", "H1", "H2"],
    ["Europe", "1.9 bn", "2.2 bn"]
  ],
  "spans": [{ "row": 0, "column": 1, "row_span": 1, "column_span": 2 }],
  "header_rows": [0, 1],
  "header_columns": [0]
}
```

The cell `2025` covers columns 1 and 2. Its text is in both slots of the first row, so the figure `2.2 bn` can be read with its 3 headings: Europe, 2025, and H2. Code that reads one column gets the right heading without a look at `spans`.

## Tell a computed cell from an entered one

In a spreadsheet each sheet is a section with the sheet's name, and its cells come as the sheet displays them. The table has 2 more fields. `top_left_cell` is the address of its first cell on the sheet, such as `B4`. `formula_cells` lists the cells that had a formula, so you know which values were computed and which were typed in.

The arithmetic of a document is not checked for you. The cells are there to check it: your code can add a column and compare the sum with the total that the document states.

## Know which sources give tables as cells

A table comes cell by cell where the source says what its rows and columns are.

| Source | How its tables come |
| - | - |
| A web page | Cell by cell. |
| A Word file or a spreadsheet | Cell by cell. |
| A PDF with structure | Cell by cell. |
| A PDF without structure | As text. |
| A scan or a photo | As text. |

`basis` on a table says where its structure came from, and `structure` means the source itself has it.

## Get the other kinds of block

`block_kinds` takes 10 kinds, and a report draws on these 5 beside the table.

| Kind | What the block has |
| - | - |
| `text` | A paragraph or a list, with bold, italic, and struck text and links as Markdown. |
| `heading` | A heading, with the section it opens. |
| `table` | The rows, the merged cells, and the headings. |
| `image` | The image's address, its alternative text, its caption, its size, and a digest of its bytes. |
| `math` | A formula as TeX. |
| `code` | A code listing, with its language where the source states it. |

The other kinds are `embed`, `media`, `divider`, and `interactive`.

A footnote stays tied to its text. The reference is in the text as `[^n]`, and the block of the note lists the blocks that cite it in `note_for`, where the document links them.

Text inside an image is not read on a source that has text of its own. If a chart matters, give the image's address to a model that reads images.

## Get the method of a paper as blocks

The method of a scientific paper is in its formulas, its code listings, and its tables. Each of them is a block of its own kind, so one request returns them without the text around them. This request asks for the formulas and the code of a paper.

```bash cURL theme={"theme":"css-variables"}
curl "https://api.getclean.ai/v1/contents/CONTENTS_ID/blocks?block_kinds=math&block_kinds=code" \
  --header "Authorization: Bearer $GETCLEAN_API_KEY"
```

```python Python theme={"theme":"css-variables"}
from getclean import GetClean

client = GetClean()

method = client.list_blocks(contents_id="CONTENTS_ID", block_kinds=["math", "code"])
for block in method:
    print(block.kind, block.text)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { GetClean } from "getclean";

const client = new GetClean();

const method = await client.listBlocks("CONTENTS_ID", { block_kinds: ["math", "code"] });
for await (const block of method) {
    console.log(block.kind, block.text);
}
```

This response is cut to 2 of its blocks and to the fields that this section explains.

```json 200 OK theme={"theme":"css-variables"}
{
  "blocks": [
    {
      "kind": "math",
      "page_number": 4,
      "text": "F_1 = \\frac{2PR}{P + R}"
    },
    {
      "kind": "code",
      "page_number": 5,
      "code_language": "python",
      "text": "def f1(precision, recall):\n    return 2 * precision * recall / (precision + recall)"
    }
  ]
}
```

A formula comes as TeX, without the signs that open and close it. Your product can typeset it, and a model reads the formula itself, not a description of it. A code listing is one block, and `code_language` names its language where the source states it. A report that says how a result was computed can then quote the formula and the code that computes it, each with its page.

A formula is a `math` block where the source has the structure of the formula. A formula that a document has only as a picture comes as flat text or not at all.

## Get the tables while you fetch

A fetch can return the blocks itself. With `formats` set to `json` and `block_kinds` set to `table`, the response has the tables of the page as blocks and nothing else of its text.

```json Request body theme={"theme":"css-variables"}
{ "url": "SOURCE_URL", "formats": ["json"], "block_kinds": ["table"] }
```

Replace `SOURCE_URL` with the address of a page or a document.

## Check what a list of blocks costs

`list_blocks` reads the stored record, so it costs nothing. The key needs the scope `contents:read`. One page of results has at most 50 blocks and 20,000 characters unless you set `page_size` and `max_characters`, and the SDKs ask for the next page as you loop.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.