# changes.list > List the change records this session retains, oldest first, with each change's actor, cause, provenance and affected blocks. Pass the returned cursor back as `after` to read only newer records; `waitMs` long-polls until at least one newer record exists. - Member path: `await doc.changes.list(…)` - Mutates document: no - Idempotency: `idempotent` - Supports tracked mode: no - Supports dry run: no ## Expected result Returns a ChangesListResult with items (oldest to newest), a resume cursor, a truncated flag when records after `after` were evicted, the session identity state and whether the session is collaborative. ## 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": { "after": { "type": "string", "minLength": 1, "description": "Cursor from a previous result. Omit to read from the oldest retained record." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum number of records to return. Defaults to 100." }, "story": { "$ref": "#/$defs/StoryLocator" }, "blockId": { "type": "string", "minLength": 1, "description": "Matches the block or any block in its split/merge lineage." }, "actorId": { "type": "string", "minLength": 1 }, "includeUpdate": { "type": "boolean", "description": "Include each record's base64 Yjs update. Defaults to false." }, "waitMs": { "type": "integer", "minimum": 0, "maximum": 30000, "description": "Wait up to this many milliseconds for at least one record after `after`. Defaults to 0." } }, "additionalProperties": false } ``` ## Output 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": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Deterministic id: identical transactions yield identical ids in every session." }, "seq": { "type": "integer", "minimum": 1 }, "revision": { "type": "string" }, "origin": { "enum": [ "local", "remote" ] }, "actor": { "oneOf": [ { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "email": { "type": "string" }, "claim": { "type": "string", "description": "Application-supplied identity claim. SuperDoc does not verify it." } }, "additionalProperties": false, "required": [ "id" ] }, { "type": "null" } ] }, "contributors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "email": { "type": "string" }, "claim": { "type": "string", "description": "Application-supplied identity claim. SuperDoc does not verify it." } }, "additionalProperties": false, "required": [ "id" ] } }, "actorType": { "oneOf": [ { "enum": [ "human", "code" ] }, { "type": "null" } ] }, "cause": { "oneOf": [ { "enum": [ "user", "api", "undo", "redo" ] }, { "type": "null" } ] }, "provenance": { "enum": [ "authored", "declared", "relayed", "unknown" ] }, "at": { "type": "object", "properties": { "declared": { "type": [ "string", "null" ] }, "observed": { "type": "string" } }, "additionalProperties": false, "required": [ "declared", "observed" ] }, "session": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "clientId": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "id", "clientId" ] }, "changeTag": { "type": "string" }, "changes": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text" }, "story": { "$ref": "#/$defs/StoryLocator" }, "blockId": { "type": "string" }, "range": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "start", "end" ] }, "inserted": { "type": "string" }, "deleted": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "story", "blockId", "range", "inserted", "deleted" ] }, { "type": "object", "properties": { "kind": { "const": "format" }, "story": { "$ref": "#/$defs/StoryLocator" }, "blockId": { "type": "string" }, "range": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "start", "end" ] }, "attributes": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "kind", "story", "blockId", "range", "attributes" ] }, { "type": "object", "properties": { "kind": { "const": "paragraph" }, "story": { "$ref": "#/$defs/StoryLocator" }, "blockId": { "type": "string" }, "properties": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "kind", "story", "blockId", "properties" ] }, { "type": "object", "properties": { "kind": { "const": "split" }, "story": { "$ref": "#/$defs/StoryLocator" }, "blockId": { "type": "string" }, "tailBlockId": { "type": "string" }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "kind", "story", "blockId", "tailBlockId", "offset" ] }, { "type": "object", "properties": { "kind": { "const": "merge" }, "story": { "$ref": "#/$defs/StoryLocator" }, "blockId": { "type": "string" }, "mergedBlockId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "story", "blockId", "mergedBlockId" ] }, { "type": "object", "properties": { "kind": { "const": "move" }, "story": { "$ref": "#/$defs/StoryLocator" }, "blockId": { "type": "string" }, "afterBlockId": { "type": [ "string", "null" ] } }, "additionalProperties": false, "required": [ "kind", "story", "blockId", "afterBlockId" ] }, { "type": "object", "properties": { "kind": { "const": "create" }, "story": { "$ref": "#/$defs/StoryLocator" }, "blockId": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "story", "blockId", "text" ] }, { "type": "object", "properties": { "kind": { "const": "remove" }, "story": { "$ref": "#/$defs/StoryLocator" }, "blockId": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "story", "blockId", "text" ] }, { "type": "object", "properties": { "kind": { "const": "table" }, "story": { "$ref": "#/$defs/StoryLocator" }, "tableId": { "type": "string" }, "detail": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "kind", "story", "tableId", "detail" ] }, { "type": "object", "properties": { "kind": { "const": "sidecar" }, "affects": { "enum": [ "comment", "trackedChange", "bookmark" ] }, "ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "kind", "affects", "ids" ] } ] } }, "update": { "type": "string", "description": "Base64 Yjs v1 update for exactly this transaction." } }, "additionalProperties": false, "required": [ "id", "seq", "revision", "origin", "actor", "actorType", "cause", "provenance", "at", "session", "changes" ] } }, "cursor": { "type": [ "string", "null" ] }, "truncated": { "type": "boolean" }, "identity": { "enum": [ "configured", "missing" ] }, "collaboration": { "type": "boolean" } }, "additionalProperties": false, "required": [ "items", "cursor", "truncated", "identity", "collaboration" ] } ``` ## Pre-apply throws - `INVALID_INPUT` - `CAPABILITY_UNAVAILABLE` ## Non-applied receipt codes - None