Remote sessions¶

Cowork sessions started on claude.ai web or mobile, which run in the cloud in Anthropic-managed environments. For sessions on users' own machines — including Claude Code — see Local sessions.

remote_sessions ¶

Remote Sessions resource group.

Remote sessions are Cowork sessions started on claude.ai web or mobile, which run in the cloud in Anthropic-managed environments. Sessions that run on users' own machines are a separate family — see local_sessions.

Wraps two endpoints, both read-only. There is deliberately no retrieve-one method: the API exposes a list and a transcript, but no GET /sessions/remote/{id}.

GET /v1/compliance/apps/sessions/remote — page of session metadata. Exposed via list and iter.
GET /v1/compliance/apps/sessions/remote/{id}/messages — one session's transcript. Exposed via list_messages and iter_messages.

Requires a Compliance Access Key with read:compliance_user_data. Admin API keys are rejected with 403.

These endpoints count against a second request budget on top of the shared Compliance API rate limit, so a 429 here can arrive well below 600 requests per minute.

Example

from claude_compliance_sdk import ComplianceClient

with ComplianceClient(api_key="sk-ant-api01-...") as client:
    for session in client.remote_sessions.iter(
        created_at_gte="2026-06-01T00:00:00Z",
    ):
        if session.status == "pending":
            continue  # No transcript until provisioning completes.
        transcript = client.remote_sessions.list_messages(session.id)
        print(session.id, len(transcript.messages.data))

RemoteSession `dataclass` ¶

Metadata for one Cowork session running in the cloud.

A session is owned by either a user or an agent, never both.

Attributes:

Name	Type	Description
`id`	`str`	Session identifier (`cse_...`).
`organization_uuid`	`str`	UUID of the organisation the session belongs to.
`created_at`	`str`	When the session was created (RFC 3339, UTC).
`updated_at`	`str`	When the session was last modified.
`status`	`str`	Lifecycle state — `pending`, `active`, `paused`, `archived`, or `failed`. A `pending` session has no transcript yet and its messages endpoint returns 404 until provisioning completes. Deleted sessions are never returned. Kept as a plain string so new states pass through.
`user`	`SessionUser \| None`	The owning user, or `None` on agent-owned sessions.
`agent_id`	`str \| None`	The owning agent (`cagt_...`), or `None` on user-owned sessions.
`started_by_user`	`SessionUser \| None`	On agent-owned sessions, the human who initiated the run — for example by starting a scheduled task. `None` on user-owned sessions.
`product_surface`	`str \| None`	Currently only `cowork_remote`. `None` when not recorded. Treat unrecognised values as an unclassified surface rather than an error.
`claude_project_id`	`str \| None`	The claude.ai project the session belongs to (`claude_proj_...`), or `None`.
`extra`	`dict[str, Any]`	Any additional fields the API adds in a later revision.

from_dict `classmethod` ¶

from_dict(body: Mapping[str, Any]) -> 'RemoteSession'

Build a RemoteSession from one decoded record.

RemoteSessionMessage `dataclass` ¶

One user or assistant turn in a remote session transcript.

Attributes:

Name	Type	Description
`id`	`str`	Message identifier (`csev_...`).
`role`	`str`	`"user"` or `"assistant"`.
`created_at`	`str`	A commit timestamp. Consecutive messages can share one or slightly invert, so preserve the returned order rather than re-sorting by this field.
`content`	`list[dict[str, Any]]`	Content blocks, each a raw dict discriminated on `type` — `text`, `tool_use`, or `tool_result`. Kept as dicts so unrecognised block types pass through. A `tool_use` block's `input` is a JSON-encoded string, and a truncated one is not valid JSON.
`sent_by_user_id`	`str \| None`	On agent-owned sessions, the user who sent this message when it is attributable. `None` otherwise, including on every assistant message.
`content_unavailable`	`bool`	`True` when the message's content could not be returned at all, for example because it exceeded size bounds.
`extra`	`dict[str, Any]`	Any additional fields the API adds in a later revision.

from_dict `classmethod` ¶

from_dict(
    body: Mapping[str, Any]
) -> "RemoteSessionMessage"

Build a RemoteSessionMessage from one decoded record.

RemoteSessionTranscript `dataclass` ¶

A page of transcript, plus the session it belongs to.

Attributes:

Name	Type	Description
`session`	`RemoteSession`	The session the messages belong to. On this endpoint its `user.email_address`, `started_by_user`, and `claude_project_id` are always `None` — read those from `list` instead.
`messages`	`OffsetPage[RemoteSessionMessage]`	One `OffsetPage` of `RemoteSessionMessage` objects.

from_dict `classmethod` ¶

from_dict(
    body: Mapping[str, Any]
) -> "RemoteSessionTranscript"

Split the envelope into a session and a page of messages.

RemoteSessions ¶

Synchronous client for the remote session endpoints.

list ¶

list(
    *,
    organization_ids: StrList | None = None,
    user_ids: StrList | None = None,
    created_at_gte: str | None = None,
    created_at_gt: str | None = None,
    created_at_lte: str | None = None,
    created_at_lt: str | None = None,
    limit: int | None = None,
    page: str | None = None
) -> OffsetPage[RemoteSession]

Fetch one page of remote session metadata, newest first.

Defaults to every organisation the key can read. There is no updated_at filter on this endpoint.

Parameters:

Name	Type	Description	Default
`organization_ids`	`StrList \| None`	Up to 500 organisation identifiers (`org_...` or UUID). `None` includes them all.	`None`
`user_ids`	`StrList \| None`	1–10 user IDs. Matches the session's owning user, so setting this excludes every agent-owned session. `None` includes them all.	`None`
`created_at_gte`	`str \| None`	`created_at >= value` (RFC 3339).	`None`
`created_at_gt`	`str \| None`	`created_at > value`.	`None`
`created_at_lte`	`str \| None`	`created_at <= value`.	`None`
`created_at_lt`	`str \| None`	`created_at < value`.	`None`
`limit`	`int \| None`	Maximum results (default 100, max 500).	`None`
`page`	`str \| None`	Opaque token from a prior response's `next_page`.	`None`

Returns:

Type	Description
`OffsetPage[RemoteSession]`	One `OffsetPage` of `RemoteSession` objects.

Raises:

Type	Description
`ValueError`	When `user_ids` or `organization_ids` is outside the API's length caps.
`RateLimitError`	These endpoints carry a second budget on top of the shared limit, so this can arrive well below 600 requests per minute.
`InsufficientScopeError`	When the key lacks `read:compliance_user_data`.

iter ¶

iter(
    *,
    organization_ids: StrList | None = None,
    user_ids: StrList | None = None,
    created_at_gte: str | None = None,
    created_at_gt: str | None = None,
    created_at_lte: str | None = None,
    created_at_lt: str | None = None,
    limit: int | None = None
) -> Iterator[RemoteSession]

Iterate every matching remote session, auto-paginating.

Same filters as list except that page is managed by the iterator.

list_messages ¶

list_messages(
    session_id: str,
    *,
    order: str | None = None,
    limit: int | None = None,
    page: str | None = None,
    tool_use_input_max_bytes: int | None = None,
    tool_result_max_bytes: int | None = None
) -> RemoteSessionTranscript

Fetch one page of a remote session's transcript.

A page can end early when the response hits its size limit, so a short page does not mean you have reached the end. Keep paginating until next_page is None.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	Session identifier (`cse_...`).	required
`order`	`str \| None`	`"asc"` (oldest first, the server default) or `"desc"`.	`None`
`limit`	`int \| None`	Maximum messages per page (default 100, max 1000).	`None`
`page`	`str \| None`	Opaque token from a prior response's `next_page`.	`None`
`tool_use_input_max_bytes`	`int \| None`	Truncate each tool-use input to this many bytes (server default 10,000). `-1` asks for the server maximum. `0` raises `ValueError`.	`None`
`tool_result_max_bytes`	`int \| None`	Truncate each text item inside a tool result the same way.	`None`

Returns:

Type	Description
`RemoteSessionTranscript`	A `RemoteSessionTranscript` — the session envelope plus one
`RemoteSessionTranscript`	page of messages.

Raises:

Type	Description
`ValueError`	When either truncation cap is `0`.
`NotFoundError`	When the session is still `pending`, does not exist, has been deleted, or is in an organisation the key cannot read.

iter_messages ¶

iter_messages(
    session_id: str,
    *,
    order: str | None = None,
    limit: int | None = None,
    tool_use_input_max_bytes: int | None = None,
    tool_result_max_bytes: int | None = None
) -> Iterator[RemoteSessionMessage]

Iterate a remote session's whole transcript, auto-paginating.

Same arguments as list_messages except that page is managed by the iterator. The session envelope is dropped.

AsyncRemoteSessions ¶

Asynchronous client for the remote session endpoints.

list `async` ¶

list(
    *,
    organization_ids: StrList | None = None,
    user_ids: StrList | None = None,
    created_at_gte: str | None = None,
    created_at_gt: str | None = None,
    created_at_lte: str | None = None,
    created_at_lt: str | None = None,
    limit: int | None = None,
    page: str | None = None
) -> OffsetPage[RemoteSession]

Async analogue of list.

iter ¶

iter(
    *,
    organization_ids: StrList | None = None,
    user_ids: StrList | None = None,
    created_at_gte: str | None = None,
    created_at_gt: str | None = None,
    created_at_lte: str | None = None,
    created_at_lt: str | None = None,
    limit: int | None = None
) -> AsyncIterator[RemoteSession]

Async analogue of iter.

list_messages `async` ¶

list_messages(
    session_id: str,
    *,
    order: str | None = None,
    limit: int | None = None,
    page: str | None = None,
    tool_use_input_max_bytes: int | None = None,
    tool_result_max_bytes: int | None = None
) -> RemoteSessionTranscript

Async analogue of list_messages.

iter_messages ¶

iter_messages(
    session_id: str,
    *,
    order: str | None = None,
    limit: int | None = None,
    tool_use_input_max_bytes: int | None = None,
    tool_result_max_bytes: int | None = None
) -> AsyncIterator[RemoteSessionMessage]

Async analogue of iter_messages.

Remote sessions¶

remote_sessions ¶

RemoteSession dataclass ¶

from_dict classmethod ¶

RemoteSessionMessage dataclass ¶

from_dict classmethod ¶

RemoteSessionTranscript dataclass ¶

from_dict classmethod ¶

RemoteSessions ¶

list ¶

iter ¶

list_messages ¶

iter_messages ¶

AsyncRemoteSessions ¶

list async ¶

iter ¶

list_messages async ¶

iter_messages ¶

RemoteSession `dataclass` ¶

from_dict `classmethod` ¶

RemoteSessionMessage `dataclass` ¶

from_dict `classmethod` ¶

RemoteSessionTranscript `dataclass` ¶

from_dict `classmethod` ¶

list `async` ¶

list_messages `async` ¶