# lists.getState

> Read the numbering-aware list state for a paragraph (numId, ilvl, abstract reference, level format). Returns null when the target is not a list item. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`.



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

## Expected result

Returns a ListsGetStateResult with `isListItem` plus numId/ilvl/abstract/numFmt metadata when present.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {
    "target": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "block"
            },
            "nodeType": {
              "const": "paragraph"
            },
            "nodeId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "nodeType",
            "nodeId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "block"
            },
            "nodeType": {
              "const": "listItem"
            },
            "nodeId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "nodeType",
            "nodeId"
          ]
        }
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "target"
  ]
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "success": {
          "const": true
        },
        "isListItem": {
          "type": "boolean"
        },
        "numId": {
          "type": [
            "string",
            "null"
          ]
        },
        "ilvl": {
          "type": "integer",
          "minimum": 0
        },
        "abstractNumId": {
          "type": [
            "string",
            "null"
          ]
        },
        "numFmt": {
          "type": [
            "string",
            "null"
          ]
        },
        "lvlText": {
          "type": [
            "string",
            "null"
          ]
        },
        "seed": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "bullet",
            "ordered",
            null
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "success",
        "isListItem",
        "ilvl"
      ]
    },
    {
      "type": "object",
      "properties": {
        "success": {
          "const": false
        },
        "failure": {
          "type": "object",
          "properties": {
            "code": {
              "enum": [
                "TARGET_NOT_FOUND",
                "CAPABILITY_UNAVAILABLE"
              ]
            },
            "message": {
              "type": "string"
            },
            "details": {}
          },
          "additionalProperties": false,
          "required": [
            "code",
            "message"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "success",
        "failure"
      ]
    }
  ]
}
```

## Pre-apply throws

- `TARGET_NOT_FOUND`
- `CAPABILITY_UNAVAILABLE`

## Non-applied receipt codes

- `TARGET_NOT_FOUND`
- `CAPABILITY_UNAVAILABLE`