> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-caio-pizzol-docs-ai-core-preset.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# blocks.list

> List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit and optional nodeType filtering.

## Summary

List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit and optional nodeType filtering.

* Operation ID: `blocks.list`
* API member path: `editor.doc.blocks.list(...)`
* Mutates document: `no`
* Idempotency: `idempotent`
* Supports tracked mode: `no`
* Supports dry run: `no`
* Deterministic target resolution: `yes`

## Expected result

Returns a BlocksListResult with total block count, an ordered array of block entries (ordinal, nodeId, nodeType, textPreview, optional text, isEmpty), and the current document revision.

## Input fields

| Field         | Type    | Required | Description |
| ------------- | ------- | -------- | ----------- |
| `includeText` | boolean | no       |             |
| `limit`       | number  | no       |             |
| `nodeTypes`   | enum\[] | no       |             |
| `offset`      | number  | no       |             |

### Example request

```json theme={null}
{
  "limit": 50,
  "offset": 0
}
```

## Output fields

| Field      | Type      | Required | Description |
| ---------- | --------- | -------- | ----------- |
| `blocks`   | object\[] | yes      |             |
| `revision` | string    | yes      |             |
| `total`    | number    | yes      |             |

### Example response

```json theme={null}
{
  "blocks": [
    {
      "nodeId": "node-def456",
      "nodeType": "paragraph",
      "ordinal": 1,
      "text": "Hello, world.",
      "textPreview": "example"
    }
  ],
  "revision": "example",
  "total": 1
}
```

## Pre-apply throws

* `INVALID_INPUT`

## Non-applied failure codes

* None

## Raw schemas

<Accordion title="Raw input schema">
  ```json theme={null}
  {
    "additionalProperties": false,
    "properties": {
      "includeText": {
        "description": "When true, includes the full flattened block text in each block entry.",
        "type": "boolean"
      },
      "limit": {
        "description": "Maximum blocks to return. Omit for all blocks.",
        "minimum": 1,
        "type": "number"
      },
      "nodeTypes": {
        "description": "Filter by block types (e.g. ['paragraph', 'heading']). Omit for all types.",
        "items": {
          "enum": [
            "paragraph",
            "heading",
            "listItem",
            "table",
            "tableRow",
            "tableCell",
            "tableOfContents",
            "image",
            "sdt"
          ]
        },
        "type": "array"
      },
      "offset": {
        "description": "Number of blocks to skip. Default: 0.",
        "minimum": 0,
        "type": "number"
      }
    },
    "type": "object"
  }
  ```
</Accordion>

<Accordion title="Raw output schema">
  ```json theme={null}
  {
    "additionalProperties": false,
    "properties": {
      "blocks": {
        "items": {
          "additionalProperties": false,
          "properties": {
            "alignment": {
              "description": "Paragraph alignment.",
              "type": "string"
            },
            "bold": {
              "description": "True if text is bold.",
              "type": "boolean"
            },
            "color": {
              "description": "Text color when explicitly set (e.g. '#000000').",
              "type": "string"
            },
            "fontFamily": {
              "description": "Font family from first text run.",
              "type": "string"
            },
            "fontSize": {
              "description": "Font size from first text run.",
              "type": "number"
            },
            "headingLevel": {
              "description": "Heading level (1-6).",
              "type": "number"
            },
            "isEmpty": {
              "type": "boolean"
            },
            "nodeId": {
              "description": "Block ID for targeting with other tools.",
              "type": "string"
            },
            "nodeType": {
              "enum": [
                "paragraph",
                "heading",
                "listItem",
                "table",
                "tableRow",
                "tableCell",
                "tableOfContents",
                "image",
                "sdt"
              ]
            },
            "ordinal": {
              "type": "number"
            },
            "ref": {
              "description": "Ref handle for this block. Pass directly to superdoc_format or superdoc_edit ref param. Only present for non-empty blocks.",
              "type": "string"
            },
            "styleId": {
              "description": "Named paragraph style.",
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "text": {
              "description": "Full flattened block text when requested with includeText.",
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "textPreview": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "ordinal",
            "nodeId",
            "nodeType"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "revision": {
        "type": "string"
      },
      "total": {
        "type": "number"
      }
    },
    "required": [
      "total",
      "blocks",
      "revision"
    ],
    "type": "object"
  }
  ```
</Accordion>