> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# trackChanges.list

> List tracked changes in the document. Body-only by default; pass `in: <StoryLocator>` or `in: "all"` to widen scope.

## Summary

List tracked changes in the document. Body-only by default; pass `in: <StoryLocator>` or `in: "all"` to widen scope.

* Operation ID: `trackChanges.list`
* API member path: `editor.doc.trackChanges.list(...)`
* Mutates document: `no`
* Idempotency: `idempotent`
* Supports tracked mode: `no`
* Supports dry run: `no`
* Deterministic target resolution: `yes`

## 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 fields

| Field | Type | Required | Description |
| - | - | - | - |
| `in` | StoryLocator \| `"all"` | no | One of: StoryLocator, `"all"` |
| `limit` | integer | no | |
| `offset` | integer | no | |
| `type` | enum | no | `"insertion"`, `"deletion"`, `"replacement"`, `"formatting"`, `"move"`, `"structural"`, `"insert"`, `"delete"`, `"format"` |

### Example request

```json theme={null}
{
  "limit": 50,
  "offset": 0
}
```

## Output fields

| Field | Type | Required | Description |
| - | - | - | - |
| `evaluatedRevision` | string | yes | |
| `items` | object\[] | yes | |
| `page` | PageInfo | yes | PageInfo |
| `page.limit` | integer | yes | |
| `page.offset` | integer | yes | |
| `page.returned` | integer | yes | |
| `total` | integer | yes | |

### Example response

```json theme={null}
{
  "evaluatedRevision": "rev-001",
  "items": [
    {
      "address": {
        "entityId": "entity-789",
        "entityType": "trackedChange",
        "kind": "entity",
        "story": {
          "kind": "story",
          "storyType": "body"
        }
      },
      "handle": {
        "ref": "handle:abc123",
        "refStability": "stable",
        "targetKind": "text"
      },
      "id": "id-001",
      "state": "open",
      "subtype": "example",
      "type": "insertion"
    }
  ],
  "page": {
    "limit": 50,
    "offset": 0,
    "returned": 1
  },
  "total": 1
}
```

## Pre-apply throws

* `INVALID_INPUT`

## Non-applied failure codes

* None

## Raw schemas

> [accordion] Raw input schema
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "in": {
>       "description": "Story scope. Omit for body only, pass a StoryLocator for a single story, or 'all' for body + every revision-capable non-body story.",
>       "oneOf": [
>         {
>           "$ref": "#/$defs/StoryLocator"
>         },
>         {
>           "const": "all"
>         }
>       ]
>     },
>     "limit": {
>       "description": "Maximum number of tracked changes to return.",
>       "type": "integer"
>     },
>     "offset": {
>       "description": "Number of tracked changes to skip for pagination.",
>       "type": "integer"
>     },
>     "type": {
>       "description": "Filter by change type. Canonical values: 'insertion', 'deletion', 'replacement', 'formatting', 'move', 'structural'. Legacy aliases 'insert', 'delete', and 'format' remain accepted during migration.",
>       "enum": [
>         "insertion",
>         "deletion",
>         "replacement",
>         "formatting",
>         "move",
>         "structural",
>         "insert",
>         "delete",
>         "format"
>       ]
>     }
>   },
>   "type": "object"
> }
> ```

> [accordion] Raw output schema
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "evaluatedRevision": {
>       "type": "string"
>     },
>     "items": {
>       "items": {
>         "additionalProperties": false,
>         "properties": {
>           "address": {
>             "$ref": "#/$defs/TrackedChangeAddress"
>           },
>           "addressKind": {
>             "enum": [
>               "entity",
>               "story-entity",
>               "unknown"
>             ]
>           },
>           "author": {
>             "type": "string"
>           },
>           "authorEmail": {
>             "type": "string"
>           },
>           "authorImage": {
>             "type": "string"
>           },
>           "canonicalizationKind": {
>             "enum": [
>               "single-word-revision",
>               "paired-word-revision",
>               "generated-runtime-id",
>               "unknown"
>             ]
>           },
>           "date": {
>             "type": "string"
>           },
>           "deletedText": {
>             "oneOf": [
>               {
>                 "type": "string"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "excerpt": {
>             "type": "string"
>           },
>           "formattingDeltaSummary": {
>             "description": "Human-readable formatting delta summary for formatting changes; null otherwise.",
>             "oneOf": [
>               {
>                 "type": "string"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "grouping": {
>             "enum": [
>               "standalone",
>               "replacement-pair",
>               "unknown"
>             ]
>           },
>           "handle": {
>             "$ref": "#/$defs/ResolvedHandle"
>           },
>           "id": {
>             "type": "string"
>           },
>           "imported": {
>             "type": "boolean"
>           },
>           "initials": {
>             "type": "string"
>           },
>           "insertedText": {
>             "oneOf": [
>               {
>                 "type": "string"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "origin": {
>             "enum": [
>               "word",
>               "google-docs",
>               "superdoc",
>               "unknown"
>             ]
>           },
>           "overlap": {
>             "additionalProperties": false,
>             "properties": {
>               "parentId": {
>                 "description": "Parent logical tracked-change id when this change is an overlap child.",
>                 "type": "string"
>               },
>               "preferredContextTarget": {
>                 "additionalProperties": false,
>                 "properties": {
>                   "id": {
>                     "description": "SuperDoc logical tracked-change id for this overlap layer.",
>                     "type": "string"
>                   },
>                   "relationship": {
>                     "enum": [
>                       "parent",
>                       "child",
>                       "standalone"
>                     ]
>                   },
>                   "type": {
>                     "description": "Canonical broad tracked-change type for this layer.",
>                     "enum": [
>                       "insertion",
>                       "deletion",
>                       "replacement",
>                       "formatting",
>                       "move",
>                       "structural",
>                       "insert",
>                       "delete",
>                       "format"
>                     ]
>                   }
>                 },
>                 "required": [
>                   "id",
>                   "type",
>                   "relationship"
>                 ],
>                 "type": "object"
>               },
>               "preferredContextTargetId": {
>                 "description": "Preferred child tracked-change id for context-menu/comment targeting.",
>                 "type": "string"
>               },
>               "relationship": {
>                 "enum": [
>                   "parent",
>                   "child",
>                   "standalone"
>                 ]
>               },
>               "visualLayers": {
>                 "description": "Ordered overlap layers, with the parent surface first and child layers after it.",
>                 "items": {
>                   "additionalProperties": false,
>                   "properties": {
>                     "id": {
>                       "description": "SuperDoc logical tracked-change id for this overlap layer.",
>                       "type": "string"
>                     },
>                     "relationship": {
>                       "enum": [
>                         "parent",
>                         "child",
>                         "standalone"
>                       ]
>                     },
>                     "type": {
>                       "description": "Canonical broad tracked-change type for this layer.",
>                       "enum": [
>                         "insertion",
>                         "deletion",
>                         "replacement",
>                         "formatting",
>                         "move",
>                         "structural",
>                         "insert",
>                         "delete",
>                         "format"
>                       ]
>                     }
>                   },
>                   "required": [
>                     "id",
>                     "type",
>                     "relationship"
>                   ],
>                   "type": "object"
>                 },
>                 "type": "array"
>               }
>             },
>             "type": "object"
>           },
>           "pairedWithChangeId": {
>             "oneOf": [
>               {
>                 "type": "string"
>               },
>               {
>                 "type": "null"
>               }
>             ]
>           },
>           "resolvableById": {
>             "type": "boolean"
>           },
>           "revisionGroupId": {
>             "type": "string"
>           },
>           "sourceIds": {
>             "additionalProperties": false,
>             "description": "Canonical multi-side source provenance. Provenance metadata only; never the canonical SuperDoc tracked-change id.",
>             "properties": {
>               "rsids": {
>                 "description": "Word revision-save ids (`w:rsidR` / `w:rsidDel`) seen on contributing wrappers.",
>                 "items": {
>                   "type": "string"
>                 },
>                 "type": "array"
>               },
>               "wordIdDelete": {
>                 "description": "Word `w:id` value from the deletion side of this logical change.",
>                 "type": "string"
>               },
>               "wordIdInsert": {
>                 "description": "Word `w:id` value from the insertion side of this logical change.",
>                 "type": "string"
>               },
>               "wordIdOther": {
>                 "description": "Word `w:id` values from other wrappers (for example moveFrom/moveTo).",
>                 "items": {
>                   "type": "string"
>                 },
>                 "type": "array"
>               }
>             },
>             "type": "object"
>           },
>           "state": {
>             "enum": [
>               "open",
>               "accepted",
>               "rejected"
>             ]
>           },
>           "storyLocator": {
>             "$ref": "#/$defs/StoryLocator"
>           },
>           "subtype": {
>             "type": "string"
>           },
>           "type": {
>             "enum": [
>               "insertion",
>               "deletion",
>               "replacement",
>               "formatting",
>               "move",
>               "structural",
>               "insert",
>               "delete",
>               "format"
>             ]
>           },
>           "wordRevisionIds": {
>             "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.",
>             "properties": {
>               "delete": {
>                 "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:del>` element when this logical change includes a deletion.",
>                 "type": "string"
>               },
>               "format": {
>                 "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:rPrChange>` element when this logical change includes a formatting revision.",
>                 "type": "string"
>               },
>               "insert": {
>                 "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:ins>` element when this logical change includes an insertion.",
>                 "type": "string"
>               }
>             },
>             "type": "object"
>           }
>         },
>         "required": [
>           "id",
>           "handle",
>           "address",
>           "type"
>         ],
>         "type": "object"
>       },
>       "type": "array"
>     },
>     "page": {
>       "$ref": "#/$defs/PageInfo"
>     },
>     "total": {
>       "minimum": 0,
>       "type": "integer"
>     }
>   },
>   "required": [
>     "evaluatedRevision",
>     "total",
>     "items",
>     "page"
>   ],
>   "type": "object"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.