# comments.list

> List all comment threads in the document.



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

## Expected result

Returns a CommentsListResult with an array of comment threads and total count.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {
    "includeResolved": {
      "type": "boolean",
      "description": "When true, includes resolved comments in results. Default: false."
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of comments to return."
    },
    "offset": {
      "type": "integer",
      "description": "Number of comments to skip for pagination."
    }
  },
  "additionalProperties": false
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "ResolvedHandle": {
      "type": "object",
      "properties": {
        "ref": {
          "type": "string"
        },
        "refStability": {
          "enum": [
            "stable",
            "ephemeral"
          ]
        },
        "targetKind": {
          "$ref": "#/$defs/TargetKind"
        }
      },
      "additionalProperties": false,
      "required": [
        "ref",
        "refStability",
        "targetKind"
      ]
    },
    "TargetKind": {
      "anyOf": [
        {
          "enum": [
            "text",
            "node",
            "list",
            "comment",
            "trackedChange",
            "table",
            "tableCell",
            "tableOfContents",
            "section",
            "sdt",
            "field"
          ]
        },
        {
          "type": "string",
          "pattern": "^ext:.+$"
        }
      ]
    },
    "CommentAddress": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "entity"
        },
        "entityType": {
          "const": "comment"
        },
        "entityId": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "entityType",
        "entityId"
      ]
    },
    "TextTarget": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "text"
        },
        "segments": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/TextSegment"
          },
          "minItems": 1
        },
        "story": {
          "$ref": "#/$defs/StoryLocator"
        },
        "coordinateSpace": {
          "$ref": "#/$defs/TextCoordinateSpace"
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "segments"
      ]
    },
    "TextSegment": {
      "type": "object",
      "properties": {
        "blockId": {
          "type": "string"
        },
        "range": {
          "$ref": "#/$defs/Range"
        }
      },
      "additionalProperties": false,
      "required": [
        "blockId",
        "range"
      ]
    },
    "Range": {
      "type": "object",
      "properties": {
        "start": {
          "type": "integer"
        },
        "end": {
          "type": "integer"
        }
      },
      "additionalProperties": false,
      "required": [
        "start",
        "end"
      ]
    },
    "StoryLocator": {
      "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "body"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "headerFooterSlot"
            },
            "section": {
              "$ref": "#/$defs/SectionAddress"
            },
            "headerFooterKind": {
              "enum": [
                "header",
                "footer"
              ]
            },
            "variant": {
              "enum": [
                "default",
                "first",
                "even"
              ]
            },
            "resolution": {
              "enum": [
                "effective",
                "explicit"
              ]
            },
            "onWrite": {
              "enum": [
                "materializeIfInherited",
                "editResolvedPart",
                "error"
              ]
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "section",
            "headerFooterKind",
            "variant"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "headerFooterPart"
            },
            "refId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "refId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "footnote"
            },
            "noteId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "noteId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "endnote"
            },
            "noteId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "noteId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "story"
            },
            "storyType": {
              "const": "textbox"
            },
            "textboxId": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "storyType",
            "textboxId"
          ]
        }
      ]
    },
    "SectionAddress": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "section"
        },
        "sectionId": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "sectionId"
      ]
    },
    "TextCoordinateSpace": {
      "enum": [
        "visible",
        "tracked"
      ]
    },
    "CommentTrackedChangeLink": {
      "type": "object",
      "properties": {
        "trackedChange": {
          "const": true
        },
        "trackedChangeId": {
          "type": "string"
        },
        "trackedChangeType": {
          "enum": [
            "insertion",
            "deletion",
            "replacement",
            "formatting",
            "move",
            "structural",
            "insert",
            "delete",
            "format"
          ]
        },
        "side": {
          "enum": [
            "inserted",
            "deleted",
            "source",
            "destination"
          ]
        },
        "trackedChangeText": {
          "type": "string"
        },
        "insertedText": {
          "type": "string"
        },
        "deletedText": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "trackedChange",
        "trackedChangeId",
        "trackedChangeType"
      ]
    },
    "PageInfo": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "minimum": 0
        },
        "offset": {
          "type": "integer",
          "minimum": 0
        },
        "returned": {
          "type": "integer",
          "minimum": 0
        }
      },
      "additionalProperties": false,
      "required": [
        "limit",
        "offset",
        "returned"
      ]
    }
  },
  "type": "object",
  "properties": {
    "evaluatedRevision": {
      "type": "string"
    },
    "total": {
      "type": "integer",
      "minimum": 0
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "handle": {
            "$ref": "#/$defs/ResolvedHandle"
          },
          "address": {
            "$ref": "#/$defs/CommentAddress"
          },
          "externalId": {
            "type": "string",
            "description": "Caller-owned durable integration id, distinct from the Word-compatible comment id."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Caller-owned JSON metadata persisted with the comment."
          },
          "importedId": {
            "type": "string"
          },
          "rawOoxmlId": {
            "type": "string",
            "description": "Durable raw OOXML source identity: the comment's w:id exactly as it appears in comments.xml. Surfaced for every catalog-backed comment, even when commentId already equals it on a clean import. Omitted for synthetic comments that never had a comments.xml carrier."
          },
          "rawOoxmlOccurrenceIndex": {
            "type": "number",
            "description": "Zero-based source occurrence among comments that share the same rawOoxmlId in comments.xml. Present only for duplicate raw OOXML ids."
          },
          "parentCommentId": {
            "type": "string"
          },
          "trackedChangeParentId": {
            "type": "string",
            "description": "SuperDoc logical tracked-change id when the comment anchor sits wholly inside exactly one active tracked change. Derived on read."
          },
          "trackedChangeThreadParentId": {
            "type": "string",
            "description": "SuperDoc logical tracked-change id whose review conversation this comment explicitly belongs to. Persisted provenance; never inferred from anchor overlap."
          },
          "trackedChangeSide": {
            "enum": [
              "inserted",
              "deleted",
              "source",
              "destination"
            ],
            "description": "Which side of the surrounding tracked change the comment anchor sits on."
          },
          "text": {
            "type": "string"
          },
          "isInternal": {
            "type": "boolean"
          },
          "status": {
            "enum": [
              "open",
              "resolved"
            ]
          },
          "target": {
            "$ref": "#/$defs/TextTarget"
          },
          "anchoredText": {
            "type": "string"
          },
          "createdTime": {
            "type": "number"
          },
          "creatorName": {
            "type": "string"
          },
          "creatorId": {
            "type": "string"
          },
          "creatorEmail": {
            "type": "string"
          },
          "creatorImage": {
            "type": "string"
          },
          "trackedChange": {
            "type": "boolean"
          },
          "trackedChangeType": {
            "enum": [
              "insertion",
              "deletion",
              "replacement",
              "formatting",
              "move",
              "structural",
              "insert",
              "delete",
              "format"
            ]
          },
          "trackedChangeDisplayType": {
            "type": [
              "string",
              "null"
            ]
          },
          "trackedChangeStory": {
            "oneOf": [
              {
                "$ref": "#/$defs/StoryLocator"
              },
              {
                "type": "null"
              }
            ]
          },
          "trackedChangeAnchorKey": {
            "type": [
              "string",
              "null"
            ]
          },
          "trackedChangeText": {
            "type": [
              "string",
              "null"
            ]
          },
          "insertedText": {
            "type": [
              "string",
              "null"
            ]
          },
          "deletedText": {
            "type": [
              "string",
              "null"
            ]
          },
          "trackedChangeLink": {
            "oneOf": [
              {
                "$ref": "#/$defs/CommentTrackedChangeLink"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "handle",
          "address",
          "status"
        ]
      }
    },
    "page": {
      "$ref": "#/$defs/PageInfo"
    }
  },
  "additionalProperties": false,
  "required": [
    "evaluatedRevision",
    "total",
    "items",
    "page"
  ]
}
```

## Pre-apply throws

- `INVALID_INPUT`

## Non-applied receipt codes

- None