# blocks.findText

> Find top-level body blocks containing a literal case-insensitive substring. Matches flattened block text, coalescing repeated hits and nested table paragraphs into one block. Scans at most 20,000 blocks inside the document host and returns compact previews without transferring full-text pages.



- Member path: `doc.blocks.findText(…)`
- Mutates document: no
- Idempotency: `idempotent`
- Supports tracked mode: no
- Supports dry run: no

## Expected result

Returns matching-block total within the scan, limited matches with zero-based ordinals and 100-character previews, firstMatchOrdinal even for limit:0, scannedBlocks, truncated, and revision. A failed read retains completed pages and reports scanError; revision is unknown if no page succeeded. Whitespace and Unicode are not normalized.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "pattern": "\\S",
      "description": "Literal case-insensitive substring. Whitespace is preserved."
    },
    "limit": {
      "type": "integer",
      "minimum": 0,
      "description": "Maximum matches. Default: 8; zero returns counts only."
    }
  },
  "additionalProperties": false,
  "required": [
    "text"
  ]
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {
    "total": {
      "type": "integer",
      "minimum": 0
    },
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ordinal": {
            "type": "integer",
            "minimum": 0,
            "description": "Zero-based top-level body ordinal."
          },
          "nodeId": {
            "type": "string"
          },
          "nodeType": {
            "enum": [
              "paragraph",
              "heading",
              "listItem",
              "table",
              "tableRow",
              "tableCell",
              "tableOfContents",
              "image",
              "sdt"
            ]
          },
          "preview": {
            "type": "string",
            "maxLength": 100
          }
        },
        "additionalProperties": false,
        "required": [
          "ordinal",
          "nodeId",
          "nodeType",
          "preview"
        ]
      }
    },
    "firstMatchOrdinal": {
      "type": "integer",
      "minimum": 0
    },
    "scanError": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "message"
      ]
    },
    "scannedBlocks": {
      "type": "integer",
      "minimum": 0,
      "maximum": 20000
    },
    "truncated": {
      "type": "boolean"
    },
    "revision": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "total",
    "matches",
    "scannedBlocks",
    "truncated",
    "revision"
  ]
}
```

## Pre-apply throws

- `INVALID_INPUT`

## Non-applied receipt codes

- None