# trackChanges.list > List tracked changes in the document. Body-only by default; pass `in: StoryLocator` or `in: "all"` to widen scope. - Member path: `doc.trackChanges.list(…)` - Mutates document: no - Idempotency: `idempotent` - Supports tracked mode: no - Supports dry run: no ## Expected result Returns a TrackChangesListResult of logical tracked-change entries with SuperDoc ids, semantic type/subtype, author/date/excerpt, revisionGroupId, flat projection fields (`grouping`, `insertedText`, `deletedText`, `formattingDeltaSummary`, `origin`, `imported`, `canonicalizationKind`, `addressKind`, `resolvableById`), optional overlap metadata, and source provenance via `sourceIds` / `wordRevisionIds`. Structural whole-table changes surface subtypes such as `table-insert` and `table-delete`. ## Input schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "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" ] } }, "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum number of tracked changes to return." }, "offset": { "type": "integer", "description": "Number of tracked changes to skip for pagination." }, "type": { "enum": [ "insertion", "deletion", "replacement", "formatting", "move", "structural", "insert", "delete", "format" ], "description": "Filter by change type. Canonical values: 'insertion', 'deletion', 'replacement', 'formatting', 'move', 'structural'. Legacy aliases 'insert', 'delete', and 'format' remain accepted during migration." }, "in": { "oneOf": [ { "$ref": "#/$defs/StoryLocator" }, { "const": "all" } ], "description": "Story scope. Omit for body only, pass a StoryLocator for a single story, or 'all' for body + every revision-capable non-body story." } }, "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:.+$" } ] }, "TrackedChangeAddress": { "type": "object", "properties": { "kind": { "const": "entity" }, "entityType": { "const": "trackedChange" }, "entityId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "entityType", "entityId" ] }, "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" ] }, "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/TrackedChangeAddress" }, "type": { "enum": [ "insertion", "deletion", "replacement", "formatting", "move", "structural", "insert", "delete", "format" ] }, "subtype": { "type": "string" }, "state": { "enum": [ "open", "accepted", "rejected" ] }, "sourceIds": { "type": "object", "properties": { "wordIdInsert": { "type": "string", "description": "Word `w:id` value from the insertion side of this logical change." }, "wordIdDelete": { "type": "string", "description": "Word `w:id` value from the deletion side of this logical change." }, "wordIdOther": { "type": "array", "items": { "type": "string" }, "description": "Word `w:id` values from other wrappers (for example moveFrom/moveTo)." }, "rsids": { "type": "array", "items": { "type": "string" }, "description": "Word revision-save ids (`w:rsidR` / `w:rsidDel`) seen on contributing wrappers." } }, "additionalProperties": false, "description": "Canonical multi-side source provenance. Provenance metadata only; never the canonical SuperDoc tracked-change id." }, "wordRevisionIds": { "type": "object", "properties": { "insert": { "type": "string", "description": "Raw imported Word OOXML revision ID (`w:id`) from a `` element when this logical change includes an insertion." }, "delete": { "type": "string", "description": "Raw imported Word OOXML revision ID (`w:id`) from a `` element when this logical change includes a deletion." }, "format": { "type": "string", "description": "Raw imported Word OOXML revision ID (`w:id`) from a `` element when this logical change includes a formatting revision." } }, "additionalProperties": false, "description": "Raw imported Word OOXML revision IDs (`w:id`) from the source document when available. This is provenance metadata, not the canonical SuperDoc tracked-change ID. Replacements may include both `insert` and `delete` IDs." }, "revisionGroupId": { "type": "string" }, "author": { "type": "string" }, "authorEmail": { "type": "string" }, "authorImage": { "type": "string" }, "initials": { "type": "string" }, "date": { "type": "string" }, "storyLocator": { "$ref": "#/$defs/StoryLocator" }, "excerpt": { "type": "string" }, "grouping": { "enum": [ "standalone", "replacement-pair", "unknown" ] }, "pairedWithChangeId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "insertedText": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "deletedText": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "formattingDeltaSummary": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable formatting delta summary for formatting changes; null otherwise." }, "listDeltas": { "type": "array", "items": { "type": "object", "properties": { "kind": { "enum": [ "list-add", "list-remove", "list-level", "list-style", "list-restart", "indent", "other-format" ], "description": "Semantic list-delta classification for this member (spec TC-LIST-004)." }, "from": { "type": "object", "properties": { "hasNumPr": { "type": "boolean", "description": "Explicit numPr element present in the property block on this side." }, "numId": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Effective list membership numId; non-positive numIds normalize to null." }, "ilvl": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Explicit ilvl value; null when the source omitted it (effective level 0)." }, "styleKind": { "oneOf": [ { "enum": [ "bullet", "number", "letter", "roman", "other" ] }, { "type": "null" } ], "description": "Resolved visual style kind via the numbering model; null when unresolvable." } }, "additionalProperties": false, "required": [ "hasNumPr", "numId", "ilvl", "styleKind" ] }, "to": { "type": "object", "properties": { "hasNumPr": { "type": "boolean", "description": "Explicit numPr element present in the property block on this side." }, "numId": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Effective list membership numId; non-positive numIds normalize to null." }, "ilvl": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Explicit ilvl value; null when the source omitted it (effective level 0)." }, "styleKind": { "oneOf": [ { "enum": [ "bullet", "number", "letter", "roman", "other" ] }, { "type": "null" } ], "description": "Resolved visual style kind via the numbering model; null when unresolvable." } }, "additionalProperties": false, "required": [ "hasNumPr", "numId", "ilvl", "styleKind" ] }, "levelDirection": { "enum": [ "indent", "outdent" ], "description": "Direction of a list-level change." }, "restartAt": { "type": "number", "description": "Restart value for a list-restart change (numbering-model derived)." } }, "additionalProperties": false, "required": [ "kind", "from", "to" ] }, "description": "Structured per-member list semantic deltas for tracked list formatting changes (spec TC-LIST-003/004); absent for non-list changes." }, "listDeltaSummary": { "type": "object", "properties": { "uniformKind": { "oneOf": [ { "enum": [ "list-add", "list-remove", "list-level", "list-style", "list-restart", "indent", "other-format" ] }, { "type": "null" } ], "description": "The single delta kind shared by every member, or null for mixed groups." }, "counts": { "type": "object", "properties": { "list-add": { "type": "number" }, "list-remove": { "type": "number" }, "list-level": { "type": "number" }, "list-style": { "type": "number" }, "list-restart": { "type": "number" }, "indent": { "type": "number" }, "other-format": { "type": "number" } }, "additionalProperties": false, "description": "Non-zero member counts per delta kind." } }, "additionalProperties": false, "required": [ "uniformKind", "counts" ] }, "targetIsListItem": { "type": "boolean", "description": "For paragraph-mark structural changes: whether the target paragraph is a direct-numbered list item." }, "listActionKind": { "enum": [ "merge-items" ], "description": "Stable presentation fact on the merge-owner deletion change (spec TC-LIST-005)." }, "origin": { "enum": [ "word", "google-docs", "superdoc", "unknown" ] }, "imported": { "type": "boolean" }, "canonicalizationKind": { "enum": [ "single-word-revision", "paired-word-revision", "generated-runtime-id", "unknown" ] }, "addressKind": { "enum": [ "entity", "story-entity", "unknown" ] }, "resolvableById": { "type": "boolean" }, "overlap": { "type": "object", "properties": { "visualLayers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "SuperDoc logical tracked-change id for this overlap layer." }, "type": { "enum": [ "insertion", "deletion", "replacement", "formatting", "move", "structural", "insert", "delete", "format" ], "description": "Canonical broad tracked-change type for this layer." }, "relationship": { "enum": [ "parent", "child", "standalone" ] } }, "additionalProperties": false, "required": [ "id", "type", "relationship" ] }, "description": "Ordered overlap layers, with the parent surface first and child layers after it." }, "preferredContextTargetId": { "type": "string", "description": "Preferred child tracked-change id for context-menu/comment targeting." }, "preferredContextTarget": { "type": "object", "properties": { "id": { "type": "string", "description": "SuperDoc logical tracked-change id for this overlap layer." }, "type": { "enum": [ "insertion", "deletion", "replacement", "formatting", "move", "structural", "insert", "delete", "format" ], "description": "Canonical broad tracked-change type for this layer." }, "relationship": { "enum": [ "parent", "child", "standalone" ] } }, "additionalProperties": false, "required": [ "id", "type", "relationship" ] }, "relationship": { "enum": [ "parent", "child", "standalone" ] }, "parentId": { "type": "string", "description": "Parent logical tracked-change id when this change is an overlap child." } }, "additionalProperties": false }, "customAttributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "namespaceUri": { "type": "string" }, "localName": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false, "required": [ "name", "namespaceUri", "localName", "value" ] }, "description": "Unknown extension attributes in document order; exact duplicates are removed and conflicting values are retained." } }, "additionalProperties": false, "required": [ "id", "handle", "address", "type" ] } }, "page": { "$ref": "#/$defs/PageInfo" } }, "additionalProperties": false, "required": [ "evaluatedRevision", "total", "items", "page" ] } ``` ## Pre-apply throws - `INVALID_INPUT` ## Non-applied receipt codes - None