Repository Public
1---2title: Messages3url: https://platform.claude.com/docs/en/api/compliance/apps/sessions/local/messages4---56# Messages78## Retrieve local session messages910**GET** `/v1/compliance/apps/sessions/local/{local_session_id}/messages`1112Read one local session's transcript, oldest-first by default.1314Retention is enforced read-side: turns at or before the child15organization's retention boundary are never returned; a session16that straddles the boundary carries one leading17`content_unavailable` placeholder (`reason: "retention_elapsed"`)18in their place. The boundary is pinned on the walk's first page and19honored for 24 hours: a cursor older than that is rejected with an20explicit 400; restart the walk to read under the current boundary.2122### Path parameters2324- `local_session_id: string`2526### Query parameters2728- `limit: optional number`2930 Maximum results (default: 100, max: 1000)3132 default: 100, maximum: 1000, minimum: 13334- `order: optional "asc" or "desc"`3536 Sort direction. `asc` (oldest-first, default) or `desc`.3738 default: asc3940 - `"asc"`4142 - `"desc"`4344- `page: optional string`4546 Opaque pagination token from a previous response's `next_page` field. Pass this to retrieve the next page of results. Clients should treat this value as an opaque string and not attempt to parse or interpret its contents, as the format may change without notice.4748- `tool_result_max_bytes: optional number`4950 Truncate each text item inside a tool result to at most this many bytes (cut on a code-point boundary). Pass `-1` to request the server maximum (approximately 1 MiB); larger values are clamped to it. `0` is not a valid value.5152 default: 10000, maximum: 2147483647, minimum: -15354- `tool_use_input_max_bytes: optional number`5556 Truncate each tool-use input to at most this many bytes (cut on a code-point boundary so the result is valid UTF-8). Pass `-1` to request the server maximum (approximately 1 MiB); larger values are clamped to it. `0` is not a valid value.5758 default: 10000, maximum: 2147483647, minimum: -15960### Headers6162- `"x-api-key": optional string`6364### Returns6566- `data: array of object`6768 Transcript turns for this page, in call order: oldest call first by default, newest call first with `order=desc`. The messages of one call carry the call's timestamp and follow each other in transcript order; a page boundary can fall between them.6970 - `type: "compliance_local_session_message"`7172 default: compliance_local_session_message7374 - `id: string`7576 Message identifier, prefixed `clsm_`. Stable for as long as the message's turn is retained: identifiers of retained turns do not change as older turns age out of the organization's retention period. The `retention_elapsed` placeholder's identifier is distinct from every retained turn's and changes only when further turns age out.7778 - `content: array of Text or ToolUse or ToolResult`7980 Content blocks within the message, discriminated on `type` (`text` / `tool_use` / `tool_result`: the same discriminator values as the claude.ai chat-messages endpoint; the tool variants omit `integration_name` and `mcp_server_url`, and `text` carries `truncated`). Extended-thinking content is never included. The request's `system` field is never included; a presence-only marker message is emitted when it was set. The request's `tools[]` definitions are never included as transcript messages. Project-level instructions (such as CLAUDE.md files) appear in the message stream as a user-role context block and are included. Empty when `provenance.type` is `content_unavailable`.8182 - `Text object`8384 Text content block.8586 - `type: "text"`8788 default: text8990 - `text: string`9192 Text content from the user or the assistant9394 - `truncated: boolean`9596 True when `text` was shortened by the server's fixed per-string bound (approximately 1 MiB), or when ancillary content the block carried (such as citations) was omitted, or when this block stands in for a non-text block whose content is not shown, or when it is an explanatory marker the server inserted (its text enclosed in square brackets, e.g. prefacing client-asserted history). There is no request parameter that raises the per-string bound.9798 default: false99100 - `ToolUse object`101102 Tool invocation requested by the assistant.103104 - `type: "tool_use"`105106 default: tool_use107108 - `id: string or null`109110 Tool-use ID, e.g. 'toolu_01AbC...'111112 - `input: string`113114 Arguments passed to the tool, as a JSON-encoded string. May be shortened (see the `truncated` field); a truncated value is cut mid-document and is not valid JSON.115116 - `name: string`117118 Name of the tool invoked119120 - `truncated: boolean`121122 True when `input` was shortened. Pass `tool_use_input_max_bytes=-1` to request the server maximum.123124 default: false125126 - `ToolResult object`127128 Result returned by a tool invocation.129130 - `type: "tool_result"`131132 default: tool_result133134 - `content: array of object`135136 Text content returned by the tool. Non-text item types are omitted and signalled via `truncated` with an in-band item-count marker.137138 - `type: "text"`139140 default: text141142 - `text: string`143144 Text returned by the tool145146 - `is_error: boolean`147148 True when the tool reported an error149150 - `name: string`151152 Name of the tool that produced this result153154 - `tool_use_id: string or null`155156 ID of the tool_use block this result responds to157158 - `truncated: boolean`159160 True when one or more text items in `content` were shortened or non-text items were omitted. Pass `tool_result_max_bytes=-1` to request the server maximum.161162 default: false163164 - `created_at: string`165166 When the message was recorded (RFC 3339, UTC)167168 format: date-time169170 - `model: string or null`171172 The model that served this assistant turn, as reported in the `model` field of the underlying Messages API response. Null on user messages and on any assistant message whose `provenance` is set: client-asserted history and synthetic markers were not produced by a model during this session, and for unavailable content the serving model is not known.173174 - `provenance: ContentUnavailable or ClientAsserted or SyntheticMarker or null`175176 Where this turn's content came from, discriminated on `type`. Null (the common case) means verified content: on an assistant message, content Claude produced during this session; on a user message, content the user sent. `content_unavailable`: the turn's content cannot be returned and `content` is empty; `reason` says why. `client_asserted`: assistant content the client supplied as conversation history; `content` shows what the model received but its authorship is not verified; never on user-role messages. `synthetic_marker`: a transcript marker the endpoint generated rather than content either party sent during the session. Both `client_asserted` and `synthetic_marker` can result from normal request or client processing, not only client modification. Callers should tolerate unrecognized `type` values.177178 - `ContentUnavailable object`179180 The turn's content cannot be returned; `content` is empty.181182 - `type: "content_unavailable"`183184 default: content_unavailable185186 - `reason: string`187188 Why this turn's content cannot be returned, e.g. `not_captured` (the content was not captured for compliance retrieval), `client_aborted` (the client closed the connection or cancelled the request before the response completed, so the response was not captured for this turn; any partial output already streamed to the client is not included; assistant-role turns only), `cmek_key_revoked` (the content is encrypted under the organization's customer-managed key and that key is unavailable), `retention_elapsed` (the content lies past the organization's retention boundary; on the placeholder standing in for every pre-boundary turn), or `oversize` (the message exceeds the server's per-message size bound even after per-block truncation). Callers should tolerate unrecognized values. `not_captured` is not proof that no record was stored: content withheld by the storage layer's fail-closed access policies carries the same reason and is deliberately indistinguishable from content that was never captured.189190 - `ClientAsserted object`191192 Assistant content the client supplied as conversation history193 rather than produced by Claude during this session. `content` shows194 what the model received but its authorship is not verified; this can195 result from normal request or client processing, not only client196 modification. Never on user-role messages.197198 - `type: "client_asserted"`199200 default: client_asserted201202 - `SyntheticMarker object`203204 A transcript marker generated by the endpoint rather than sent by205 either party during the session. Marker messages indicate that the206 prompt history diverged from what was captured, that the request's207 `system` field was present but is not shown, or that earlier turns208 that a request re-sent as history were withheld because they cannot209 be dated against the child organization's data-retention period210 (only for organizations with a finite retention period; the request's211 new user input after its last assistant turn is not affected). The212 marker's text names the cause. Markers that report a mismatch with213 captured history can result from normal request or client processing,214 not only client modification.215216 - `type: "synthetic_marker"`217218 default: synthetic_marker219220 - `role: "assistant" or "user"`221222 Message sender (`user` or `assistant`)223224 - `"assistant"`225226 - `"user"`227228- `next_page: string or null`229230 Opaque pagination cursor (prefixed `page_`) for the next page. Null when there is no further page. Treat as an opaque string; the format may change without notice.231232- `session: object`233234 The local session the messages belong to. `user.email_address` is always null on this endpoint; the messages endpoint does not resolve email addresses.235236 - `type: "compliance_local_session"`237238 default: compliance_local_session239240 - `id: string`241242 Local session identifier, prefixed `clls_`. Unique within the parent organization. Treat as an opaque string; the format may change without notice.243244 - `created_at: string`245246 Timestamp of the session's first retained inference call (RFC 3339, UTC). When a session's activity spans the child organization's retention boundary, calls older than the boundary are no longer reflected, so this value is the timestamp of the earliest retained call: always strictly after the boundary, never the boundary itself.247248 format: date-time249250 - `organization_uuid: string`251252 UUID of the child organization the session belongs to253254 - `product_surface: string or null`255256 The product the session ran in: `cowork` (Cowork in Claude Desktop on the user's machine), `claude_code` (Claude Code), `claude_science` (Claude Science), or one of `office_agents/excel`, `office_agents/powerpoint`, `office_agents/word`, and `office_agents/outlook` (Claude for Microsoft 365, by app; `office_agents` alone when the app is not identified). New values appear as coverage expands; treat unrecognized values as opaque. `null` when the surface was not recorded.257258 - `truncated: boolean`259260 True when the session has more inference calls than the service can return for one session (100,000). The messages endpoint then returns only the session's earliest calls, up to that many, and ends before the session does; `updated_at` is a lower bound on the latest call and can differ between the list and retrieve endpoints. False for every session within that bound.261262 default: false263264 - `updated_at: string`265266 Timestamp of the session's last retained inference call (RFC 3339, UTC). Always at or after `created_at`. When a session's activity spans the child organization's retention boundary, calls older than the boundary are no longer reflected — but because retention removes only the oldest calls, this value (unlike `created_at`) is unaffected until the entire session has aged out. On the list endpoint this value is a lower bound: for a session still active at a page or `created_at.lt` window boundary it can momentarily lag the session's true last activity. Retrieving the session, or its messages, always reflects the exact latest retained call.267268 format: date-time269270 - `user: object`271272 The authenticated user at the time of the session. Always set; `user.id` is always populated. `user.email_address` is null when the user's account has been deleted or the user is no longer a member of an organization the key may read.273274 - `id: string`275276 User identifier (tagged ID, prefixed `user_`). Always set, so attribution survives after the user's account is deleted or the user leaves the organizations the key may read.277278 - `email_address: string or null`279280 User's email address. Null when the user's account has been deleted or the user is no longer a member of an organization the key may read. The messages endpoint does not resolve email addresses; this field is always null there.281282 - `workspace_id: string or null`283284 Workspace identifier (tagged ID, prefixed `wrkspc_`). Null for sessions not attributed to a workspace.285286### Example287288```bash289curl https://api.anthropic.com/v1/compliance/apps/sessions/local/$LOCAL_SESSION_ID/messages \290 -H 'anthropic-version: 2023-06-01' \291 -H "Authorization: Bearer $ANTHROPIC_COMPLIANCE_API_KEY"292```293294#### Response (200)295296```json297{298 "data": [299 {300 "id": "clsm_eyJ2IjoxLCJsIjoi…",301 "content": [302 {303 "text": "text",304 "truncated": true,305 "type": "text"306 }307 ],308 "created_at": "2025-03-12T18:22:41.123456Z",309 "model": "claude-opus-5",310 "provenance": {311 "reason": "not_captured",312 "type": "content_unavailable"313 },314 "role": "assistant",315 "type": "compliance_local_session_message"316 }317 ],318 "next_page": "page_eyJ2IjoxLCJmIjoibSIs…",319 "session": {320 "id": "clls_eyJ2IjoxLCJvIjoiOWEx…",321 "created_at": "2025-03-12T18:22:41.123456Z",322 "organization_uuid": "a1b2c3d4-e5f6-4789-a012-3456789abcde",323 "product_surface": "cowork",324 "truncated": true,325 "type": "compliance_local_session",326 "updated_at": "2025-03-12T18:22:41.123456Z",327 "user": {328 "id": "user_01WCz1FkmYMm4gnmykNKUu3Q",329 "email_address": "jane.doe@example.com"330 },331 "workspace_id": "wrkspc_01SvYKoWVRVHoEbwESNvzYdR"332 }333}334```335336## Domain types337338### Message List Response339340- `MessageListResponse object`341342 A single user or assistant turn in a local session transcript.343344 - `type: "compliance_local_session_message"`345346 default: compliance_local_session_message347348 - `id: string`349350 Message identifier, prefixed `clsm_`. Stable for as long as the message's turn is retained: identifiers of retained turns do not change as older turns age out of the organization's retention period. The `retention_elapsed` placeholder's identifier is distinct from every retained turn's and changes only when further turns age out.351352 - `content: array of Text or ToolUse or ToolResult`353354 Content blocks within the message, discriminated on `type` (`text` / `tool_use` / `tool_result`: the same discriminator values as the claude.ai chat-messages endpoint; the tool variants omit `integration_name` and `mcp_server_url`, and `text` carries `truncated`). Extended-thinking content is never included. The request's `system` field is never included; a presence-only marker message is emitted when it was set. The request's `tools[]` definitions are never included as transcript messages. Project-level instructions (such as CLAUDE.md files) appear in the message stream as a user-role context block and are included. Empty when `provenance.type` is `content_unavailable`.355356 - `Text object`357358 Text content block.359360 - `type: "text"`361362 default: text363364 - `text: string`365366 Text content from the user or the assistant367368 - `truncated: boolean`369370 True when `text` was shortened by the server's fixed per-string bound (approximately 1 MiB), or when ancillary content the block carried (such as citations) was omitted, or when this block stands in for a non-text block whose content is not shown, or when it is an explanatory marker the server inserted (its text enclosed in square brackets, e.g. prefacing client-asserted history). There is no request parameter that raises the per-string bound.371372 default: false373374 - `ToolUse object`375376 Tool invocation requested by the assistant.377378 - `type: "tool_use"`379380 default: tool_use381382 - `id: string or null`383384 Tool-use ID, e.g. 'toolu_01AbC...'385386 - `input: string`387388 Arguments passed to the tool, as a JSON-encoded string. May be shortened (see the `truncated` field); a truncated value is cut mid-document and is not valid JSON.389390 - `name: string`391392 Name of the tool invoked393394 - `truncated: boolean`395396 True when `input` was shortened. Pass `tool_use_input_max_bytes=-1` to request the server maximum.397398 default: false399400 - `ToolResult object`401402 Result returned by a tool invocation.403404 - `type: "tool_result"`405406 default: tool_result407408 - `content: array of object`409410 Text content returned by the tool. Non-text item types are omitted and signalled via `truncated` with an in-band item-count marker.411412 - `type: "text"`413414 default: text415416 - `text: string`417418 Text returned by the tool419420 - `is_error: boolean`421422 True when the tool reported an error423424 - `name: string`425426 Name of the tool that produced this result427428 - `tool_use_id: string or null`429430 ID of the tool_use block this result responds to431432 - `truncated: boolean`433434 True when one or more text items in `content` were shortened or non-text items were omitted. Pass `tool_result_max_bytes=-1` to request the server maximum.435436 default: false437438 - `created_at: string`439440 When the message was recorded (RFC 3339, UTC)441442 format: date-time443444 - `model: string or null`445446 The model that served this assistant turn, as reported in the `model` field of the underlying Messages API response. Null on user messages and on any assistant message whose `provenance` is set: client-asserted history and synthetic markers were not produced by a model during this session, and for unavailable content the serving model is not known.447448 - `provenance: ContentUnavailable or ClientAsserted or SyntheticMarker or null`449450 Where this turn's content came from, discriminated on `type`. Null (the common case) means verified content: on an assistant message, content Claude produced during this session; on a user message, content the user sent. `content_unavailable`: the turn's content cannot be returned and `content` is empty; `reason` says why. `client_asserted`: assistant content the client supplied as conversation history; `content` shows what the model received but its authorship is not verified; never on user-role messages. `synthetic_marker`: a transcript marker the endpoint generated rather than content either party sent during the session. Both `client_asserted` and `synthetic_marker` can result from normal request or client processing, not only client modification. Callers should tolerate unrecognized `type` values.451452 - `ContentUnavailable object`453454 The turn's content cannot be returned; `content` is empty.455456 - `type: "content_unavailable"`457458 default: content_unavailable459460 - `reason: string`461462 Why this turn's content cannot be returned, e.g. `not_captured` (the content was not captured for compliance retrieval), `client_aborted` (the client closed the connection or cancelled the request before the response completed, so the response was not captured for this turn; any partial output already streamed to the client is not included; assistant-role turns only), `cmek_key_revoked` (the content is encrypted under the organization's customer-managed key and that key is unavailable), `retention_elapsed` (the content lies past the organization's retention boundary; on the placeholder standing in for every pre-boundary turn), or `oversize` (the message exceeds the server's per-message size bound even after per-block truncation). Callers should tolerate unrecognized values. `not_captured` is not proof that no record was stored: content withheld by the storage layer's fail-closed access policies carries the same reason and is deliberately indistinguishable from content that was never captured.463464 - `ClientAsserted object`465466 Assistant content the client supplied as conversation history467 rather than produced by Claude during this session. `content` shows468 what the model received but its authorship is not verified; this can469 result from normal request or client processing, not only client470 modification. Never on user-role messages.471472 - `type: "client_asserted"`473474 default: client_asserted475476 - `SyntheticMarker object`477478 A transcript marker generated by the endpoint rather than sent by479 either party during the session. Marker messages indicate that the480 prompt history diverged from what was captured, that the request's481 `system` field was present but is not shown, or that earlier turns482 that a request re-sent as history were withheld because they cannot483 be dated against the child organization's data-retention period484 (only for organizations with a finite retention period; the request's485 new user input after its last assistant turn is not affected). The486 marker's text names the cause. Markers that report a mismatch with487 captured history can result from normal request or client processing,488 not only client modification.489490 - `type: "synthetic_marker"`491492 default: synthetic_marker493494 - `role: "assistant" or "user"`495496 Message sender (`user` or `assistant`)497498 - `"assistant"`499500 - `"user"`501