---
title: "outline.read: Read the outline — Note kit command — Kition"
description: "Lists the headings with their level, line (from 1), heading path, section range and word count, a page at a time (`limit`, then `cursor` from `next`). Use it to find the path or line that section commands take."
canonical: "https://developer.kition.ai/docs/kits/note/commands/outline.read"
---

> Canonical HTML: [https://developer.kition.ai/docs/kits/note/commands/outline.read](https://developer.kition.ai/docs/kits/note/commands/outline.read)

# outline.read

**Read the outline.** Lists the headings with their level, line (from 1), heading path, section range and word count, a page at a time (`limit`, then `cursor` from `next`). Use it to find the path or line that section commands take.

- Kit: Note 0.3.0 (Markdown (.md)); reference: [Note kit commands](https://developer.kition.ai/docs/kits/note.md)
- Changes the document: no

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | `string` | no | Where the previous page ended (its next value). |
| `limit` | `integer` | no | The most headings to answer (default 200, at most 1000). |

## Call through note_run

```text
note_run {
  "path": "<file>.md",
  "steps": [{ "command": "outline.read" }]
}
```

The required parameters, with placeholders for their types: not a tested example. Optional: `cursor`, `limit`. note_run answers the step’s result in `completed[i].result`.

## Result

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `headings` | `object[]` | yes | This page's headings, in document order. |
| `next` | `string` | no | The cursor of the next page; absent on the last page. |
| `total` | `integer` | yes | How many headings the note has. |

```json
{
  "additionalProperties": false,
  "properties": {
    "headings": {
      "description": "This page's headings, in document order.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "from": {
            "description": "Where its section starts (Unicode characters).",
            "type": "integer"
          },
          "level": {
            "description": "1 to 6.",
            "type": "integer"
          },
          "line": {
            "description": "The heading's line, from 1.",
            "type": "integer"
          },
          "path": {
            "description": "The heading's path: the plain texts of the headings above it and its own.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "to": {
            "description": "Where its section ends, subsections included (exclusive).",
            "type": "integer"
          },
          "words": {
            "description": "The words under it, subsections included.",
            "type": "integer"
          }
        },
        "required": [
          "from",
          "level",
          "line",
          "path",
          "to",
          "words"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "next": {
      "description": "The cursor of the next page; absent on the last page.",
      "type": "string"
    },
    "total": {
      "description": "How many headings the note has.",
      "type": "integer"
    }
  },
  "required": [
    "headings",
    "total"
  ],
  "type": "object"
}
```

## Parameter schema

```json
{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "description": "Where the previous page ended (its next value).",
      "type": "string"
    },
    "limit": {
      "description": "The most headings to answer (default 200, at most 1000).",
      "type": "integer"
    }
  },
  "type": "object"
}
```

Generated from kition-sdk packages/script/kits/note.ts and the kit itself (kition-note@69e14d9).
