# Sessions ## Create Session `$client->beta->sessions->create(Agent agent, string environmentID, ?array metadata, ?list resources, ?string title, ?list vaultIDs, ?list betas): BetaManagedAgentsSession` **post** `/v1/sessions` Create Session ### Parameters - `agent: Agent` Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. - `environmentID: string` ID of the `environment` defining the container configuration for this session. - `metadata?:optional array` Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `resources?:optional list` Resources (e.g. repositories, files) to mount into the session's container. - `title?:optional string` Human-readable session title. - `vaultIDs?:optional list` Vault IDs for stored credentials the agent can use during the session. - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `BetaManagedAgentsSession` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for a session. - `Status status` SessionStatus enum - `?string title` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for a session across all turns. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Example ```php beta->sessions->create( agent: 'agent_011CZkYpogX7uDKUyvBTophP', environmentID: 'env_011CZkZ9X2dpNyB7HsEFoRfW', metadata: ['foo' => 'string'], resources: [ [ 'fileID' => 'file_011CNha8iCJcU1wXNR6q4V8w', 'type' => 'file', 'mountPath' => '/uploads/receipt.pdf', ], ], title: 'Order #1234 inquiry', vaultIDs: ['string'], betas: ['message-batches-2024-09-24'], ); var_dump($betaManagedAgentsSession); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ## List Sessions `$client->beta->sessions->list(?string agentID, ?int agentVersion, ?\Datetime createdAtGt, ?\Datetime createdAtGte, ?\Datetime createdAtLt, ?\Datetime createdAtLte, ?string deploymentID, ?bool includeArchived, ?int limit, ?string memoryStoreID, ?Order order, ?string page, ?list statuses, ?list betas): PageCursor` **get** `/v1/sessions` List Sessions ### Parameters - `agentID?:optional string` Filter sessions created with this agent ID. - `agentVersion?:optional int` Filter by agent version. Only applies when agent_id is also set. - `createdAtGt?:optional \Datetime` Return sessions created after this time (exclusive). - `createdAtGte?:optional \Datetime` Return sessions created at or after this time (inclusive). - `createdAtLt?:optional \Datetime` Return sessions created before this time (exclusive). - `createdAtLte?:optional \Datetime` Return sessions created at or before this time (inclusive). - `deploymentID?:optional string` Filter sessions created by this deployment ID. - `includeArchived?:optional bool` When true, includes archived sessions. Default: false (exclude archived). - `limit?:optional int` Maximum number of results to return. - `memoryStoreID?:optional string` Filter sessions whose resources contain a memory_store with this memory store ID. - `order?:optional Order` Sort direction for results, ordered by created_at. Defaults to desc (newest first). - `page?:optional string` Opaque pagination cursor from a previous response. - `statuses?:optional list` Filter by session status. Repeat the parameter to match any of multiple statuses. - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `BetaManagedAgentsSession` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for a session. - `Status status` SessionStatus enum - `?string title` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for a session across all turns. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Example ```php beta->sessions->list( agentID: 'agent_id', agentVersion: 0, createdAtGt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), deploymentID: 'deployment_id', includeArchived: true, limit: 0, memoryStoreID: 'memory_store_id', order: 'asc', page: 'page', statuses: ['rescheduling'], betas: ['message-batches-2024-09-24'], ); var_dump($page); ``` #### Response ```json { "data": [ { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Session `$client->beta->sessions->retrieve(string sessionID, ?list betas): BetaManagedAgentsSession` **get** `/v1/sessions/{session_id}` Get Session ### Parameters - `sessionID: string` - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `BetaManagedAgentsSession` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for a session. - `Status status` SessionStatus enum - `?string title` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for a session across all turns. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Example ```php beta->sessions->retrieve( 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: ['message-batches-2024-09-24'] ); var_dump($betaManagedAgentsSession); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ## Update Session `$client->beta->sessions->update(string sessionID, ?BetaManagedAgentsSessionAgentUpdate agent, ?array metadata, ?string title, ?list vaultIDs, ?list betas): BetaManagedAgentsSession` **post** `/v1/sessions/{session_id}` Update Session ### Parameters - `sessionID: string` - `agent?:optional BetaManagedAgentsSessionAgentUpdate` Mid-session agent configuration update. Only `tools` and `mcp_servers` are updatable. Full replacement: the provided array becomes the new value. To preserve existing entries, GET the session, modify the array, and POST it back. - `metadata?:optional array` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. - `title?:optional string` Human-readable session title. - `vaultIDs?:optional list` Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `BetaManagedAgentsSession` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for a session. - `Status status` SessionStatus enum - `?string title` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for a session across all turns. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Example ```php beta->sessions->update( 'sesn_011CZkZAtmR3yMPDzynEDxu7', agent: [ 'mcpServers' => [ [ 'name' => 'example-mcp', 'type' => 'url', 'url' => 'https://example-server.modelcontextprotocol.io/sse', ], ], 'tools' => [ [ 'type' => 'agent_toolset_20260401', 'configs' => [ [ 'name' => 'bash', 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'], ], ], 'defaultConfig' => [ 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'] ], ], ], ], metadata: ['foo' => 'string'], title: 'Order #1234 inquiry', vaultIDs: ['string'], betas: ['message-batches-2024-09-24'], ); var_dump($betaManagedAgentsSession); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ## Delete Session `$client->beta->sessions->delete(string sessionID, ?list betas): BetaManagedAgentsDeletedSession` **delete** `/v1/sessions/{session_id}` Delete Session ### Parameters - `sessionID: string` - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `BetaManagedAgentsDeletedSession` - `string id` - `Type type` ### Example ```php beta->sessions->delete( 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: ['message-batches-2024-09-24'] ); var_dump($betaManagedAgentsDeletedSession); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "type": "session_deleted" } ``` ## Archive Session `$client->beta->sessions->archive(string sessionID, ?list betas): BetaManagedAgentsSession` **post** `/v1/sessions/{session_id}/archive` Archive Session ### Parameters - `sessionID: string` - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `BetaManagedAgentsSession` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for a session. - `Status status` SessionStatus enum - `?string title` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for a session across all turns. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Example ```php beta->sessions->archive( 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: ['message-batches-2024-09-24'] ); var_dump($betaManagedAgentsSession); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ## Domain Types ### Beta Managed Agents Agent Params - `BetaManagedAgentsAgentParams` - `string id` The `agent` ID. - `Type type` - `?int version` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. ### Beta Managed Agents Branch Checkout - `BetaManagedAgentsBranchCheckout` - `string name` Branch name to check out. - `Type type` ### Beta Managed Agents Cache Creation Usage - `BetaManagedAgentsCacheCreationUsage` - `?int ephemeral1hInputTokens` Tokens used to create 1-hour ephemeral cache entries. - `?int ephemeral5mInputTokens` Tokens used to create 5-minute ephemeral cache entries. ### Beta Managed Agents Commit Checkout - `BetaManagedAgentsCommitCheckout` - `string sha` Full commit SHA to check out. - `Type type` ### Beta Managed Agents Deleted Session - `BetaManagedAgentsDeletedSession` - `string id` - `Type type` ### Beta Managed Agents File Resource Params - `BetaManagedAgentsFileResourceParams` - `string fileID` ID of a previously uploaded file. - `Type type` - `?string mountPath` Mount path in the container. Defaults to `/mnt/session/uploads/`. ### Beta Managed Agents GitHub Repository Resource Params - `BetaManagedAgentsGitHubRepositoryResourceParams` - `string authorizationToken` GitHub authorization token used to clone the repository. - `Type type` - `string url` Github URL of the repository - `?Checkout checkout` Branch or commit to check out. Defaults to the repository's default branch. - `?string mountPath` Mount path in the container. Defaults to `/workspace/`. ### Beta Managed Agents Memory Store Resource Param - `BetaManagedAgentsMemoryStoreResourceParam` - `string memoryStoreID` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `Type type` - `?Access access` Access mode for an attached memory store. - `?string instructions` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. ### Beta Managed Agents Multiagent - `BetaManagedAgentsMultiagent` - `list agents` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `Type type` ### Beta Managed Agents Multiagent Params - `BetaManagedAgentsMultiagentParams` - `list agents` Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1). - `Type type` ### Beta Managed Agents Multiagent Roster Entry Params - `BetaManagedAgentsMultiagentRosterEntryParams` - `string` - `BetaManagedAgentsAgentParams` - `string id` The `agent` ID. - `Type type` - `?int version` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. - `BetaManagedAgentsMultiagentSelfParams` - `Type type` ### Beta Managed Agents Outcome Evaluation Resource - `BetaManagedAgentsOutcomeEvaluationResource` - `?\Datetime completedAt` A timestamp in RFC 3339 format - `string description` What the agent should produce. - `?string explanation` Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable. - `int iteration` 0-indexed revision cycle the outcome is currently on. - `string outcomeID` Server-generated outc_ ID for this outcome. - `string result` Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. - `Type type` ### Beta Managed Agents Session - `BetaManagedAgentsSession` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for a session. - `Status status` SessionStatus enum - `?string title` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for a session across all turns. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. ### Beta Managed Agents Session Agent - `BetaManagedAgentsSessionAgent` - `string id` - `?string description` - `list mcpServers` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsSessionMultiagentCoordinator multiagent` Resolved coordinator topology with full agent definitions for each roster member. - `string name` - `list skills` - `?string system` - `list tools` - `Type type` - `int version` ### Beta Managed Agents Session Agent Update - `BetaManagedAgentsSessionAgentUpdate` - `?list mcpServers` Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. - `?list tools` Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. ### Beta Managed Agents Session Multiagent Coordinator - `BetaManagedAgentsSessionMultiagentCoordinator` - `list agents` Full `agent` definitions the coordinator may spawn as session threads. - `Type type` ### Beta Managed Agents Session Stats - `BetaManagedAgentsSessionStats` - `?float activeSeconds` Cumulative time in seconds the session spent in running status. Excludes idle time. - `?float durationSeconds` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. ### Beta Managed Agents Session Updated Event - `BetaManagedAgentsSessionUpdatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. ### Beta Managed Agents Session Usage - `BetaManagedAgentsSessionUsage` - `?BetaManagedAgentsCacheCreationUsage cacheCreation` Prompt-cache creation token usage broken down by cache lifetime. - `?int cacheReadInputTokens` Total tokens read from prompt cache. - `?int inputTokens` Total input tokens consumed across all turns. - `?int outputTokens` Total output tokens generated across all turns. ### Beta Managed Agents System Content Block - `BetaManagedAgentsSystemContentBlock` - `string text` The text content. - `Type type` ### Beta Managed Agents System Message Event - `BetaManagedAgentsSystemMessageEvent` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format ### Beta Managed Agents User Tool Result Event - `BetaManagedAgentsUserToolResultEvent` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. # Events ## List Events `$client->beta->sessions->events->list(string sessionID, ?\Datetime createdAtGt, ?\Datetime createdAtGte, ?\Datetime createdAtLt, ?\Datetime createdAtLte, ?int limit, ?Order order, ?string page, ?list types, ?list betas): PageCursor` **get** `/v1/sessions/{session_id}/events` List Events ### Parameters - `sessionID: string` - `createdAtGt?:optional \Datetime` Return events created after this time (exclusive). - `createdAtGte?:optional \Datetime` Return events created at or after this time (inclusive). - `createdAtLt?:optional \Datetime` Return events created before this time (exclusive). - `createdAtLte?:optional \Datetime` Return events created at or before this time (inclusive). - `limit?:optional int` Query parameter for limit - `order?:optional Order` Sort direction for results, ordered by created_at. Defaults to asc (chronological). - `page?:optional string` Opaque pagination cursor from a previous response's next_page. - `types?:optional list` Filter by event type. Values match the `type` field on returned events (for example, `user.message` or `agent.tool_use`). Omit to return all event types. - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsSessionEvent` - `ManagedAgentsUserMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `ManagedAgentsUserInterruptEvent` - `string id` Unique identifier for this event. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `ManagedAgentsUserToolConfirmationEvent` - `string id` Unique identifier for this event. - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `ManagedAgentsUserCustomToolResultEvent` - `string id` Unique identifier for this event. - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `ManagedAgentsAgentCustomToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `ManagedAgentsAgentMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentThinkingEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentMCPToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentMCPToolResultEvent` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentToolResultEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentThreadMessageReceivedEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `ManagedAgentsAgentThreadMessageSentEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `Type type` - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `ManagedAgentsAgentThreadContextCompactedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionErrorEvent` - `string id` Unique identifier for this event. - `Error error` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRescheduledEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRunningEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusIdleEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionStatusTerminatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadCreatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `Type type` - `ManagedAgentsSpanOutcomeEvaluationStartEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationEndEvent` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `Type type` - `ManagedAgentsSpanModelUsage usage` Token usage for a single model request. - `ManagedAgentsSpanModelRequestStartEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanModelRequestEndEvent` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for a single model request. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsUserDefineOutcomeEvent` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` - `ManagedAgentsSessionDeletedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadStatusRunningEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `Type type` - `ManagedAgentsSessionThreadStatusIdleEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionThreadStatusTerminatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `Type type` - `BetaManagedAgentsUserToolResultEvent` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `ManagedAgentsSessionThreadStatusRescheduledEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `Type type` - `BetaManagedAgentsSessionUpdatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `BetaManagedAgentsSystemMessageEvent` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format ### Example ```php beta->sessions->events->list( 'sesn_011CZkZAtmR3yMPDzynEDxu7', createdAtGt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), limit: 0, order: 'asc', page: 'page', types: ['string'], betas: ['message-batches-2024-09-24'], ); var_dump($page); ``` #### Response ```json { "data": [ { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" }, { "id": "sevt_011CZkZHPq1jCdq5lbRTjiVnz", "content": [ { "text": "Let me look up order #1234 for you.", "type": "text" } ], "processed_at": "2026-03-15T10:00:00Z", "type": "agent.message" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Send Events `$client->beta->sessions->events->send(string sessionID, list events, ?list betas): ManagedAgentsSendSessionEvents` **post** `/v1/sessions/{session_id}/events` Send Events ### Parameters - `sessionID: string` - `events: list` Events to send to the `session`. - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsSendSessionEvents` - `?list data` Sent events ### Example ```php beta->sessions->events->send( 'sesn_011CZkZAtmR3yMPDzynEDxu7', events: [ [ 'content' => [['text' => 'Where is my order #1234?', 'type' => 'text']], 'type' => 'user.message', ], ], betas: ['message-batches-2024-09-24'], ); var_dump($betaManagedAgentsSendSessionEvents); ``` #### Response ```json { "data": [ { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ] } ``` ## Stream Events `$client->beta->sessions->events->stream(string sessionID, ?list betas): ManagedAgentsStreamSessionEvents` **get** `/v1/sessions/{session_id}/events/stream` Stream Events ### Parameters - `sessionID: string` - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsStreamSessionEvents` - `ManagedAgentsUserMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `ManagedAgentsUserInterruptEvent` - `string id` Unique identifier for this event. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `ManagedAgentsUserToolConfirmationEvent` - `string id` Unique identifier for this event. - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `ManagedAgentsUserCustomToolResultEvent` - `string id` Unique identifier for this event. - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `ManagedAgentsAgentCustomToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `ManagedAgentsAgentMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentThinkingEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentMCPToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentMCPToolResultEvent` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentToolResultEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentThreadMessageReceivedEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `ManagedAgentsAgentThreadMessageSentEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `Type type` - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `ManagedAgentsAgentThreadContextCompactedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionErrorEvent` - `string id` Unique identifier for this event. - `Error error` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRescheduledEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRunningEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusIdleEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionStatusTerminatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadCreatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `Type type` - `ManagedAgentsSpanOutcomeEvaluationStartEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationEndEvent` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `Type type` - `ManagedAgentsSpanModelUsage usage` Token usage for a single model request. - `ManagedAgentsSpanModelRequestStartEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanModelRequestEndEvent` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for a single model request. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsUserDefineOutcomeEvent` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` - `ManagedAgentsSessionDeletedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadStatusRunningEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `Type type` - `ManagedAgentsSessionThreadStatusIdleEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionThreadStatusTerminatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `Type type` - `BetaManagedAgentsUserToolResultEvent` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `ManagedAgentsSessionThreadStatusRescheduledEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `Type type` - `BetaManagedAgentsSessionUpdatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `BetaManagedAgentsSystemMessageEvent` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format ### Example ```php beta ->sessions ->events ->streamStream( 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: ['message-batches-2024-09-24'] ); var_dump($betaManagedAgentsStreamSessionEvents); ``` #### Response ```json { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ``` ## Domain Types ### Beta Managed Agents Agent Custom Tool Use Event - `ManagedAgentsAgentCustomToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. ### Beta Managed Agents Agent MCP Tool Result Event - `ManagedAgentsAgentMCPToolResultEvent` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. ### Beta Managed Agents Agent MCP Tool Use Event - `ManagedAgentsAgentMCPToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. ### Beta Managed Agents Agent Message Event - `ManagedAgentsAgentMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Agent Thinking Event - `ManagedAgentsAgentThinkingEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Agent Thread Context Compacted Event - `ManagedAgentsAgentThreadContextCompactedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Agent Thread Message Received Event - `ManagedAgentsAgentThreadMessageReceivedEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. ### Beta Managed Agents Agent Thread Message Sent Event - `ManagedAgentsAgentThreadMessageSentEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `Type type` - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. ### Beta Managed Agents Agent Tool Result Event - `ManagedAgentsAgentToolResultEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. ### Beta Managed Agents Agent Tool Use Event - `ManagedAgentsAgentToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. ### Beta Managed Agents Base64 Document Source - `ManagedAgentsBase64DocumentSource` - `string data` Base64-encoded document data. - `string mediaType` MIME type of the document (e.g., "application/pdf"). - `Type type` ### Beta Managed Agents Base64 Image Source - `ManagedAgentsBase64ImageSource` - `string data` Base64-encoded image data. - `string mediaType` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `Type type` ### Beta Managed Agents Billing Error - `ManagedAgentsBillingError` - `string message` Human-readable error description. - `RetryStatus retryStatus` What the client should do next in response to this error. - `Type type` ### Beta Managed Agents Credential Host Unreachable Error - `ManagedAgentsCredentialHostUnreachableError` - `string credentialID` ID of the affected credential. - `string message` Human-readable error description. - `RetryStatus retryStatus` What the client should do next in response to this error. - `Type type` - `string vaultID` ID of the vault containing the affected credential. ### Beta Managed Agents Document Block - `ManagedAgentsDocumentBlock` - `Source source` Union type for document source variants. - `Type type` - `?string context` Additional context about the document for the model. - `?string title` The title of the document. ### Beta Managed Agents Event Params - `ManagedAgentsEventParams` - `ManagedAgentsUserMessageEventParams` - `list content` Array of content blocks for the user message. - `Type type` - `ManagedAgentsUserInterruptEventParams` - `Type type` - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `ManagedAgentsUserToolConfirmationEventParams` - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `ManagedAgentsUserCustomToolResultEventParams` - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsUserDefineOutcomeEventParams` - `string description` What the agent should produce. This is the task specification. - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` - `?int maxIterations` Eval→revision cycles before giving up. Default 3, max 20. - `ManagedAgentsUserToolResultEventParams` - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsSystemMessageEventParams` - `list content` System content blocks to append. Text-only. - `Type type` ### Beta Managed Agents File Document Source - `ManagedAgentsFileDocumentSource` - `string fileID` ID of a previously uploaded file. - `Type type` ### Beta Managed Agents File Image Source - `ManagedAgentsFileImageSource` - `string fileID` ID of a previously uploaded file. - `Type type` ### Beta Managed Agents File Rubric - `ManagedAgentsFileRubric` - `string fileID` ID of the rubric file. - `Type type` ### Beta Managed Agents File Rubric Params - `ManagedAgentsFileRubricParams` - `string fileID` ID of the rubric file. - `Type type` ### Beta Managed Agents Image Block - `ManagedAgentsImageBlock` - `Source source` Union type for image source variants. - `Type type` ### Beta Managed Agents MCP Authentication Failed Error - `ManagedAgentsMCPAuthenticationFailedError` - `string mcpServerName` Name of the MCP server that failed authentication. - `string message` Human-readable error description. - `RetryStatus retryStatus` What the client should do next in response to this error. - `Type type` ### Beta Managed Agents MCP Connection Failed Error - `ManagedAgentsMCPConnectionFailedError` - `string mcpServerName` Name of the MCP server that failed to connect. - `string message` Human-readable error description. - `RetryStatus retryStatus` What the client should do next in response to this error. - `Type type` ### Beta Managed Agents Model Overloaded Error - `ManagedAgentsModelOverloadedError` - `string message` Human-readable error description. - `RetryStatus retryStatus` What the client should do next in response to this error. - `Type type` ### Beta Managed Agents Model Rate Limited Error - `ManagedAgentsModelRateLimitedError` - `string message` Human-readable error description. - `RetryStatus retryStatus` What the client should do next in response to this error. - `Type type` ### Beta Managed Agents Model Request Failed Error - `ManagedAgentsModelRequestFailedError` - `string message` Human-readable error description. - `RetryStatus retryStatus` What the client should do next in response to this error. - `Type type` ### Beta Managed Agents Plain Text Document Source - `ManagedAgentsPlainTextDocumentSource` - `string data` The plain text content. - `MediaType mediaType` MIME type of the text content. Must be "text/plain". - `Type type` ### Beta Managed Agents Retry Status Exhausted - `ManagedAgentsRetryStatusExhausted` - `Type type` ### Beta Managed Agents Retry Status Retrying - `ManagedAgentsRetryStatusRetrying` - `Type type` ### Beta Managed Agents Retry Status Terminal - `ManagedAgentsRetryStatusTerminal` - `Type type` ### Beta Managed Agents Search Result Block - `ManagedAgentsSearchResultBlock` - `ManagedAgentsSearchResultCitations citations` Citation settings for a search result. - `list content` Array of text content blocks from the search result. - `string source` The URL source of the search result. - `string title` The title of the search result. - `Type type` ### Beta Managed Agents Search Result Citations - `ManagedAgentsSearchResultCitations` - `bool enabled` Whether citations are enabled for this search result. ### Beta Managed Agents Search Result Content - `ManagedAgentsSearchResultContent` - `string text` The text content. - `Type type` ### Beta Managed Agents Send Session Events - `ManagedAgentsSendSessionEvents` - `?list data` Sent events ### Beta Managed Agents Session Deleted Event - `ManagedAgentsSessionDeletedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Session End Turn - `ManagedAgentsSessionEndTurn` - `Type type` ### Beta Managed Agents Session Error Event - `ManagedAgentsSessionErrorEvent` - `string id` Unique identifier for this event. - `Error error` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Session Event - `ManagedAgentsSessionEvent` - `ManagedAgentsUserMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `ManagedAgentsUserInterruptEvent` - `string id` Unique identifier for this event. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `ManagedAgentsUserToolConfirmationEvent` - `string id` Unique identifier for this event. - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `ManagedAgentsUserCustomToolResultEvent` - `string id` Unique identifier for this event. - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `ManagedAgentsAgentCustomToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `ManagedAgentsAgentMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentThinkingEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentMCPToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentMCPToolResultEvent` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentToolResultEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentThreadMessageReceivedEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `ManagedAgentsAgentThreadMessageSentEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `Type type` - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `ManagedAgentsAgentThreadContextCompactedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionErrorEvent` - `string id` Unique identifier for this event. - `Error error` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRescheduledEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRunningEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusIdleEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionStatusTerminatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadCreatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `Type type` - `ManagedAgentsSpanOutcomeEvaluationStartEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationEndEvent` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `Type type` - `ManagedAgentsSpanModelUsage usage` Token usage for a single model request. - `ManagedAgentsSpanModelRequestStartEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanModelRequestEndEvent` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for a single model request. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsUserDefineOutcomeEvent` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` - `ManagedAgentsSessionDeletedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadStatusRunningEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `Type type` - `ManagedAgentsSessionThreadStatusIdleEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionThreadStatusTerminatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `Type type` - `BetaManagedAgentsUserToolResultEvent` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `ManagedAgentsSessionThreadStatusRescheduledEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `Type type` - `BetaManagedAgentsSessionUpdatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `BetaManagedAgentsSystemMessageEvent` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format ### Beta Managed Agents Session Requires Action - `ManagedAgentsSessionRequiresAction` - `list eventIDs` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `Type type` ### Beta Managed Agents Session Retries Exhausted - `ManagedAgentsSessionRetriesExhausted` - `Type type` ### Beta Managed Agents Session Status Idle Event - `ManagedAgentsSessionStatusIdleEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` ### Beta Managed Agents Session Status Rescheduled Event - `ManagedAgentsSessionStatusRescheduledEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Session Status Running Event - `ManagedAgentsSessionStatusRunningEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Session Status Terminated Event - `ManagedAgentsSessionStatusTerminatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Session Thread Created Event - `ManagedAgentsSessionThreadCreatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `Type type` ### Beta Managed Agents Session Thread Status Idle Event - `ManagedAgentsSessionThreadStatusIdleEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` ### Beta Managed Agents Session Thread Status Rescheduled Event - `ManagedAgentsSessionThreadStatusRescheduledEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `Type type` ### Beta Managed Agents Session Thread Status Running Event - `ManagedAgentsSessionThreadStatusRunningEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `Type type` ### Beta Managed Agents Session Thread Status Terminated Event - `ManagedAgentsSessionThreadStatusTerminatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `Type type` ### Beta Managed Agents Span Model Request End Event - `ManagedAgentsSpanModelRequestEndEvent` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for a single model request. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Span Model Request Start Event - `ManagedAgentsSpanModelRequestStartEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Span Model Usage - `ManagedAgentsSpanModelUsage` - `int cacheCreationInputTokens` Tokens used to create prompt cache in this request. - `int cacheReadInputTokens` Tokens read from prompt cache in this request. - `int inputTokens` Input tokens consumed by this request. - `int outputTokens` Output tokens generated by this request. - `?Speed speed` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. ### Beta Managed Agents Span Outcome Evaluation End Event - `ManagedAgentsSpanOutcomeEvaluationEndEvent` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `Type type` - `ManagedAgentsSpanModelUsage usage` Token usage for a single model request. ### Beta Managed Agents Span Outcome Evaluation Ongoing Event - `ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Span Outcome Evaluation Start Event - `ManagedAgentsSpanOutcomeEvaluationStartEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` ### Beta Managed Agents Stream Session Events - `ManagedAgentsStreamSessionEvents` - `ManagedAgentsUserMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `ManagedAgentsUserInterruptEvent` - `string id` Unique identifier for this event. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `ManagedAgentsUserToolConfirmationEvent` - `string id` Unique identifier for this event. - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `ManagedAgentsUserCustomToolResultEvent` - `string id` Unique identifier for this event. - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `ManagedAgentsAgentCustomToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `ManagedAgentsAgentMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentThinkingEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentMCPToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentMCPToolResultEvent` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentToolResultEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentThreadMessageReceivedEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `ManagedAgentsAgentThreadMessageSentEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `Type type` - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `ManagedAgentsAgentThreadContextCompactedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionErrorEvent` - `string id` Unique identifier for this event. - `Error error` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRescheduledEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRunningEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusIdleEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionStatusTerminatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadCreatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `Type type` - `ManagedAgentsSpanOutcomeEvaluationStartEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationEndEvent` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `Type type` - `ManagedAgentsSpanModelUsage usage` Token usage for a single model request. - `ManagedAgentsSpanModelRequestStartEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanModelRequestEndEvent` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for a single model request. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsUserDefineOutcomeEvent` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` - `ManagedAgentsSessionDeletedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadStatusRunningEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `Type type` - `ManagedAgentsSessionThreadStatusIdleEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionThreadStatusTerminatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `Type type` - `BetaManagedAgentsUserToolResultEvent` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `ManagedAgentsSessionThreadStatusRescheduledEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `Type type` - `BetaManagedAgentsSessionUpdatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `BetaManagedAgentsSystemMessageEvent` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format ### Beta Managed Agents System Message Event Params - `ManagedAgentsSystemMessageEventParams` - `list content` System content blocks to append. Text-only. - `Type type` ### Beta Managed Agents Text Block - `ManagedAgentsTextBlock` - `string text` The text content. - `Type type` ### Beta Managed Agents Text Rubric - `ManagedAgentsTextRubric` - `string content` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `Type type` ### Beta Managed Agents Text Rubric Params - `ManagedAgentsTextRubricParams` - `string content` Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters. - `Type type` ### Beta Managed Agents Unknown Error - `ManagedAgentsUnknownError` - `string message` Human-readable error description. - `RetryStatus retryStatus` What the client should do next in response to this error. - `Type type` ### Beta Managed Agents URL Document Source - `ManagedAgentsURLDocumentSource` - `Type type` - `string url` URL of the document to fetch. ### Beta Managed Agents URL Image Source - `ManagedAgentsURLImageSource` - `Type type` - `string url` URL of the image to fetch. ### Beta Managed Agents User Custom Tool Result Event - `ManagedAgentsUserCustomToolResultEvent` - `string id` Unique identifier for this event. - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. ### Beta Managed Agents User Custom Tool Result Event Params - `ManagedAgentsUserCustomToolResultEventParams` - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. ### Beta Managed Agents User Define Outcome Event - `ManagedAgentsUserDefineOutcomeEvent` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` ### Beta Managed Agents User Define Outcome Event Params - `ManagedAgentsUserDefineOutcomeEventParams` - `string description` What the agent should produce. This is the task specification. - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` - `?int maxIterations` Eval→revision cycles before giving up. Default 3, max 20. ### Beta Managed Agents User Interrupt Event - `ManagedAgentsUserInterruptEvent` - `string id` Unique identifier for this event. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. ### Beta Managed Agents User Interrupt Event Params - `ManagedAgentsUserInterruptEventParams` - `Type type` - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. ### Beta Managed Agents User Message Event - `ManagedAgentsUserMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format ### Beta Managed Agents User Message Event Params - `ManagedAgentsUserMessageEventParams` - `list content` Array of content blocks for the user message. - `Type type` ### Beta Managed Agents User Tool Confirmation Event - `ManagedAgentsUserToolConfirmationEvent` - `string id` Unique identifier for this event. - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. ### Beta Managed Agents User Tool Confirmation Event Params - `ManagedAgentsUserToolConfirmationEventParams` - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. ### Beta Managed Agents User Tool Result Event Params - `ManagedAgentsUserToolResultEventParams` - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. # Resources ## Add Session Resource `$client->beta->sessions->resources->add(string sessionID, string fileID, Type type, ?string mountPath, ?list betas): ManagedAgentsFileResource` **post** `/v1/sessions/{session_id}/resources` Add Session Resource ### Parameters - `sessionID: string` - `fileID: string` ID of a previously uploaded file. - `type: Type` - `mountPath?:optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsFileResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format ### Example ```php beta->sessions->resources->add( 'sesn_011CZkZAtmR3yMPDzynEDxu7', fileID: 'file_011CNha8iCJcU1wXNR6q4V8w', type: 'file', mountPath: '/uploads/receipt.pdf', betas: ['message-batches-2024-09-24'], ); var_dump($betaManagedAgentsFileResource); ``` #### Response ```json { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" } ``` ## List Session Resources `$client->beta->sessions->resources->list(string sessionID, ?int limit, ?string page, ?list betas): PageCursor` **get** `/v1/sessions/{session_id}/resources` List Session Resources ### Parameters - `sessionID: string` - `limit?:optional int` Maximum number of resources to return per page (max 1000). If omitted, returns all resources. - `page?:optional string` Opaque cursor from a previous response's next_page field. - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsSessionResource` - `ManagedAgentsGitHubRepositoryResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string url` - `?Checkout checkout` - `ManagedAgentsFileResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `ManagedAgentsMemoryStoreResource` - `string memoryStoreID` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `Type type` - `?Access access` Access mode for an attached memory store. - `?string description` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `?string instructions` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `?string mountPath` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `?string name` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Example ```php beta->sessions->resources->list( 'sesn_011CZkZAtmR3yMPDzynEDxu7', limit: 0, page: 'page', betas: ['message-batches-2024-09-24'], ); var_dump($page); ``` #### Response ```json { "data": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Session Resource `$client->beta->sessions->resources->retrieve(string resourceID, string sessionID, ?list betas): ResourceGetResponse` **get** `/v1/sessions/{session_id}/resources/{resource_id}` Get Session Resource ### Parameters - `sessionID: string` - `resourceID: string` - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ResourceGetResponse` - `ManagedAgentsGitHubRepositoryResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string url` - `?Checkout checkout` - `ManagedAgentsFileResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `ManagedAgentsMemoryStoreResource` - `string memoryStoreID` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `Type type` - `?Access access` Access mode for an attached memory store. - `?string description` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `?string instructions` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `?string mountPath` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `?string name` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Example ```php beta->sessions->resources->retrieve( 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: ['message-batches-2024-09-24'], ); var_dump($resource); ``` #### Response ```json { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ``` ## Update Session Resource `$client->beta->sessions->resources->update(string resourceID, string sessionID, string authorizationToken, ?list betas): ResourceUpdateResponse` **post** `/v1/sessions/{session_id}/resources/{resource_id}` Update Session Resource ### Parameters - `sessionID: string` - `resourceID: string` - `authorizationToken: string` New authorization token for the resource. Currently only `github_repository` resources support token rotation. - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ResourceUpdateResponse` - `ManagedAgentsGitHubRepositoryResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string url` - `?Checkout checkout` - `ManagedAgentsFileResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `ManagedAgentsMemoryStoreResource` - `string memoryStoreID` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `Type type` - `?Access access` Access mode for an attached memory store. - `?string description` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `?string instructions` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `?string mountPath` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `?string name` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Example ```php beta->sessions->resources->update( 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', authorizationToken: 'ghp_exampletoken', betas: ['message-batches-2024-09-24'], ); var_dump($resource); ``` #### Response ```json { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ``` ## Delete Session Resource `$client->beta->sessions->resources->delete(string resourceID, string sessionID, ?list betas): ManagedAgentsDeleteSessionResource` **delete** `/v1/sessions/{session_id}/resources/{resource_id}` Delete Session Resource ### Parameters - `sessionID: string` - `resourceID: string` - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsDeleteSessionResource` - `string id` - `Type type` ### Example ```php beta ->sessions ->resources ->delete( 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: ['message-batches-2024-09-24'], ); var_dump($betaManagedAgentsDeleteSessionResource); ``` #### Response ```json { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "type": "session_resource_deleted" } ``` ## Domain Types ### Beta Managed Agents Delete Session Resource - `ManagedAgentsDeleteSessionResource` - `string id` - `Type type` ### Beta Managed Agents File Resource - `ManagedAgentsFileResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format ### Beta Managed Agents GitHub Repository Resource - `ManagedAgentsGitHubRepositoryResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string url` - `?Checkout checkout` ### Beta Managed Agents Memory Store Resource - `ManagedAgentsMemoryStoreResource` - `string memoryStoreID` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `Type type` - `?Access access` Access mode for an attached memory store. - `?string description` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `?string instructions` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `?string mountPath` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `?string name` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Beta Managed Agents Session Resource - `ManagedAgentsSessionResource` - `ManagedAgentsGitHubRepositoryResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string url` - `?Checkout checkout` - `ManagedAgentsFileResource` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `ManagedAgentsMemoryStoreResource` - `string memoryStoreID` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `Type type` - `?Access access` Access mode for an attached memory store. - `?string description` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `?string instructions` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `?string mountPath` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `?string name` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. # Threads ## List Session Threads `$client->beta->sessions->threads->list(string sessionID, ?int limit, ?string page, ?list betas): PageCursor` **get** `/v1/sessions/{session_id}/threads` List Session Threads ### Parameters - `sessionID: string` - `limit?:optional int` Maximum results per page. Defaults to 1000. - `page?:optional string` Opaque pagination cursor from a previous response's next_page. Forward-only. - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsSessionThread` - `string id` Unique identifier for this thread. - `BetaManagedAgentsSessionThreadAgent agent` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string parentThreadID` Parent thread that spawned this thread. Null for the primary thread. - `string sessionID` The session this thread belongs to. - `?ManagedAgentsSessionThreadStats stats` Timing statistics for a session thread. - `ManagedAgentsSessionThreadStatus status` SessionThreadStatus enum - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `?ManagedAgentsSessionThreadUsage usage` Cumulative token usage for a session thread across all turns. ### Example ```php beta->sessions->threads->list( 'sesn_011CZkZAtmR3yMPDzynEDxu7', limit: 0, page: 'page', betas: ['message-batches-2024-09-24'], ); var_dump($page); ``` #### Response ```json { "data": [ { "id": "sthr_011CZkZVWa6oIjw0rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "parent_thread_id": null, "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "stats": { "active_seconds": 0, "duration_seconds": 0, "startup_seconds": 0 }, "status": "idle", "type": "session_thread", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Session Thread `$client->beta->sessions->threads->retrieve(string threadID, string sessionID, ?list betas): ManagedAgentsSessionThread` **get** `/v1/sessions/{session_id}/threads/{thread_id}` Get Session Thread ### Parameters - `sessionID: string` - `threadID: string` - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsSessionThread` - `string id` Unique identifier for this thread. - `BetaManagedAgentsSessionThreadAgent agent` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string parentThreadID` Parent thread that spawned this thread. Null for the primary thread. - `string sessionID` The session this thread belongs to. - `?ManagedAgentsSessionThreadStats stats` Timing statistics for a session thread. - `ManagedAgentsSessionThreadStatus status` SessionThreadStatus enum - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `?ManagedAgentsSessionThreadUsage usage` Cumulative token usage for a session thread across all turns. ### Example ```php beta->sessions->threads->retrieve( 'sthr_011CZkZVWa6oIjw0rgXZpnBt', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: ['message-batches-2024-09-24'], ); var_dump($betaManagedAgentsSessionThread); ``` #### Response ```json { "id": "sthr_011CZkZVWa6oIjw0rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "parent_thread_id": null, "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "stats": { "active_seconds": 0, "duration_seconds": 0, "startup_seconds": 0 }, "status": "idle", "type": "session_thread", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ``` ## Archive Session Thread `$client->beta->sessions->threads->archive(string threadID, string sessionID, ?list betas): ManagedAgentsSessionThread` **post** `/v1/sessions/{session_id}/threads/{thread_id}/archive` Archive Session Thread ### Parameters - `sessionID: string` - `threadID: string` - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsSessionThread` - `string id` Unique identifier for this thread. - `BetaManagedAgentsSessionThreadAgent agent` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string parentThreadID` Parent thread that spawned this thread. Null for the primary thread. - `string sessionID` The session this thread belongs to. - `?ManagedAgentsSessionThreadStats stats` Timing statistics for a session thread. - `ManagedAgentsSessionThreadStatus status` SessionThreadStatus enum - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `?ManagedAgentsSessionThreadUsage usage` Cumulative token usage for a session thread across all turns. ### Example ```php beta->sessions->threads->archive( 'sthr_011CZkZVWa6oIjw0rgXZpnBt', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: ['message-batches-2024-09-24'], ); var_dump($betaManagedAgentsSessionThread); ``` #### Response ```json { "id": "sthr_011CZkZVWa6oIjw0rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "parent_thread_id": null, "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "stats": { "active_seconds": 0, "duration_seconds": 0, "startup_seconds": 0 }, "status": "idle", "type": "session_thread", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ``` ## Domain Types ### Beta Managed Agents Session Thread - `ManagedAgentsSessionThread` - `string id` Unique identifier for this thread. - `BetaManagedAgentsSessionThreadAgent agent` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. - `?\Datetime archivedAt` A timestamp in RFC 3339 format - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string parentThreadID` Parent thread that spawned this thread. Null for the primary thread. - `string sessionID` The session this thread belongs to. - `?ManagedAgentsSessionThreadStats stats` Timing statistics for a session thread. - `ManagedAgentsSessionThreadStatus status` SessionThreadStatus enum - `Type type` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `?ManagedAgentsSessionThreadUsage usage` Cumulative token usage for a session thread across all turns. ### Beta Managed Agents Session Thread Stats - `ManagedAgentsSessionThreadStats` - `?float activeSeconds` Cumulative time in seconds the thread spent actively running. Excludes idle time. - `?float durationSeconds` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. - `?float startupSeconds` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. ### Beta Managed Agents Session Thread Status - `ManagedAgentsSessionThreadStatus` - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` ### Beta Managed Agents Session Thread Usage - `ManagedAgentsSessionThreadUsage` - `?BetaManagedAgentsCacheCreationUsage cacheCreation` Prompt-cache creation token usage broken down by cache lifetime. - `?int cacheReadInputTokens` Total tokens read from prompt cache. - `?int inputTokens` Total input tokens consumed across all turns. - `?int outputTokens` Total output tokens generated across all turns. ### Beta Managed Agents Stream Session Thread Events - `ManagedAgentsStreamSessionThreadEvents` - `ManagedAgentsUserMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `ManagedAgentsUserInterruptEvent` - `string id` Unique identifier for this event. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `ManagedAgentsUserToolConfirmationEvent` - `string id` Unique identifier for this event. - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `ManagedAgentsUserCustomToolResultEvent` - `string id` Unique identifier for this event. - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `ManagedAgentsAgentCustomToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `ManagedAgentsAgentMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentThinkingEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentMCPToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentMCPToolResultEvent` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentToolResultEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentThreadMessageReceivedEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `ManagedAgentsAgentThreadMessageSentEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `Type type` - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `ManagedAgentsAgentThreadContextCompactedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionErrorEvent` - `string id` Unique identifier for this event. - `Error error` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRescheduledEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRunningEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusIdleEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionStatusTerminatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadCreatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `Type type` - `ManagedAgentsSpanOutcomeEvaluationStartEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationEndEvent` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `Type type` - `ManagedAgentsSpanModelUsage usage` Token usage for a single model request. - `ManagedAgentsSpanModelRequestStartEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanModelRequestEndEvent` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for a single model request. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsUserDefineOutcomeEvent` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` - `ManagedAgentsSessionDeletedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadStatusRunningEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `Type type` - `ManagedAgentsSessionThreadStatusIdleEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionThreadStatusTerminatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `Type type` - `BetaManagedAgentsUserToolResultEvent` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `ManagedAgentsSessionThreadStatusRescheduledEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `Type type` - `BetaManagedAgentsSessionUpdatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `BetaManagedAgentsSystemMessageEvent` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format # Events ## List Session Thread Events `$client->beta->sessions->threads->events->list(string threadID, string sessionID, ?int limit, ?string page, ?list betas): PageCursor` **get** `/v1/sessions/{session_id}/threads/{thread_id}/events` List Session Thread Events ### Parameters - `sessionID: string` - `threadID: string` - `limit?:optional int` Query parameter for limit - `page?:optional string` Query parameter for page - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsSessionEvent` - `ManagedAgentsUserMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `ManagedAgentsUserInterruptEvent` - `string id` Unique identifier for this event. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `ManagedAgentsUserToolConfirmationEvent` - `string id` Unique identifier for this event. - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `ManagedAgentsUserCustomToolResultEvent` - `string id` Unique identifier for this event. - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `ManagedAgentsAgentCustomToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `ManagedAgentsAgentMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentThinkingEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentMCPToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentMCPToolResultEvent` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentToolResultEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentThreadMessageReceivedEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `ManagedAgentsAgentThreadMessageSentEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `Type type` - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `ManagedAgentsAgentThreadContextCompactedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionErrorEvent` - `string id` Unique identifier for this event. - `Error error` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRescheduledEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRunningEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusIdleEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionStatusTerminatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadCreatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `Type type` - `ManagedAgentsSpanOutcomeEvaluationStartEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationEndEvent` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `Type type` - `ManagedAgentsSpanModelUsage usage` Token usage for a single model request. - `ManagedAgentsSpanModelRequestStartEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanModelRequestEndEvent` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for a single model request. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsUserDefineOutcomeEvent` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` - `ManagedAgentsSessionDeletedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadStatusRunningEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `Type type` - `ManagedAgentsSessionThreadStatusIdleEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionThreadStatusTerminatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `Type type` - `BetaManagedAgentsUserToolResultEvent` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `ManagedAgentsSessionThreadStatusRescheduledEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `Type type` - `BetaManagedAgentsSessionUpdatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `BetaManagedAgentsSystemMessageEvent` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format ### Example ```php beta->sessions->threads->events->list( 'sthr_011CZkZVWa6oIjw0rgXZpnBt', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', limit: 0, page: 'page', betas: ['message-batches-2024-09-24'], ); var_dump($page); ``` #### Response ```json { "data": [ { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ], "next_page": "next_page" } ``` ## Stream Session Thread Events `$client->beta->sessions->threads->events->stream(string threadID, string sessionID, ?list betas): ManagedAgentsStreamSessionThreadEvents` **get** `/v1/sessions/{session_id}/threads/{thread_id}/stream` Stream Session Thread Events ### Parameters - `sessionID: string` - `threadID: string` - `betas?:optional list` Optional header to specify the beta version(s) you want to use. ### Returns - `ManagedAgentsStreamSessionThreadEvents` - `ManagedAgentsUserMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `ManagedAgentsUserInterruptEvent` - `string id` Unique identifier for this event. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `ManagedAgentsUserToolConfirmationEvent` - `string id` Unique identifier for this event. - `Result result` UserToolConfirmationResult enum - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `ManagedAgentsUserCustomToolResultEvent` - `string id` Unique identifier for this event. - `string customToolUseID` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `ManagedAgentsAgentCustomToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `ManagedAgentsAgentMessageEvent` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentThinkingEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsAgentMCPToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentMCPToolResultEvent` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentToolUseEvent` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?EvaluatedPermission evaluatedPermission` AgentEvaluatedPermission enum - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `ManagedAgentsAgentToolResultEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `ManagedAgentsAgentThreadMessageReceivedEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `ManagedAgentsAgentThreadMessageSentEvent` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `Type type` - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `ManagedAgentsAgentThreadContextCompactedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionErrorEvent` - `string id` Unique identifier for this event. - `Error error` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRescheduledEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusRunningEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionStatusIdleEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionStatusTerminatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadCreatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `Type type` - `ManagedAgentsSpanOutcomeEvaluationStartEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationEndEvent` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `Type type` - `ManagedAgentsSpanModelUsage usage` Token usage for a single model request. - `ManagedAgentsSpanModelRequestStartEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanModelRequestEndEvent` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for a single model request. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsUserDefineOutcomeEvent` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Rubric rubric` Rubric for grading the quality of an outcome. - `Type type` - `ManagedAgentsSessionDeletedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `ManagedAgentsSessionThreadStatusRunningEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `Type type` - `ManagedAgentsSessionThreadStatusIdleEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `StopReason stopReason` The agent completed its turn naturally and is ready for the next user message. - `Type type` - `ManagedAgentsSessionThreadStatusTerminatedEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `Type type` - `BetaManagedAgentsUserToolResultEvent` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `Type type` - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` A timestamp in RFC 3339 format - `?string sessionThreadID` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `ManagedAgentsSessionThreadStatusRescheduledEvent` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` A timestamp in RFC 3339 format - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `Type type` - `BetaManagedAgentsSessionUpdatedEvent` - `string id` Unique identifier for this event. - `\Datetime processedAt` A timestamp in RFC 3339 format - `Type type` - `?BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `BetaManagedAgentsSystemMessageEvent` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `Type type` - `?\Datetime processedAt` A timestamp in RFC 3339 format ### Example ```php beta ->sessions ->threads ->events ->streamStream( 'sthr_011CZkZVWa6oIjw0rgXZpnBt', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: ['message-batches-2024-09-24'], ); var_dump($betaManagedAgentsStreamSessionThreadEvents); ``` #### Response ```json { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ```