--- title: "Get Session" method: GET path: "/workspaces/{workspace_id}/agent/sessions/{session_id}" tags: ["agent-sessions"] --- # Get Session `GET /workspaces/{workspace_id}/agent/sessions/{session_id}` ## Request - Base URL: `https://platform.tracecat.com/api` - URL: `https://platform.tracecat.com/api/workspaces/{workspace_id}/agent/sessions/{session_id}` - Auth: one of: - API key in cookie `fastapiusersauth` - HTTP bearer Get an agent session or legacy chat with its message history. Legacy chats have is_readonly=True. ## Path parameters - `session_id` string, uuid, required - `workspace_id` string, uuid, required ## Response `200` Successful Response - union - AgentSessionReadWithMessages: Response schema for agent session with message history. - `id` string, uuid, required - `workspace_id` string, uuid, required - `title` string, required - `created_by` string, uuid, nullable, required - `is_readonly` boolean: Whether the requesting actor can modify this session - `entity_type` 'case' | 'agent_preset' | 'agent_preset_builder' | 'copilot' | 'workflow' | 'approval' | 'external_channel', required: The type of entity associated with an agent session. Determines the context and behavior of the session: - CASE: Chat attached to a Case entity for investigation - AGENT_PRESET: Live chat testing a preset configuration - AGENT_PRESET_BUILDER: Builder chat for editing/configuring a preset - WORKSPACE_CHAT: Workspace-level chat assistant (wire value: copilot) - WORKFLOW: Workflow-initiated agent run (from action) - APPROVAL: Inbox approval continuation (hidden from main chat list) - EXTERNAL_CHANNEL: External channel session (e.g. Slack thread) - `entity_id` string, uuid, required - `channel_context` object, nullable, required - `tools` string[], nullable, required - `mcp_integrations` string[], nullable, required - `agent_preset_id` string, uuid, nullable, required - `agent_preset_version_id` string, uuid, nullable, required - `agents_binding` ResolvedAgentsConfig: Persisted immutable resolved child refs. - `enabled` boolean - `subagents` ResolvedAttachedSubagentRef[] - `preset` string, required - `preset_version` integer, nullable - `name` string, nullable - `description` string, nullable - `max_turns` integer, nullable - `preset_id` string, uuid, required - `preset_version_id` string, uuid, required - `backend_id` string - `capabilities` AgentSessionCapabilities: Optional controls the session's backend supports. - `steering` boolean: Whether a running turn accepts steering messages - `withdrawing` boolean: Whether a running turn can take back pending user messages - `listing_pending` boolean: Whether the session can list messages the model has not read - `harness_type` string, nullable, required - `last_error` string, nullable - `last_stream_id` string, nullable - `artifacts` Artifact[] - union - CaseArtifact: Case artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'case' - `severity` 'unknown' | 'informational' | 'low' | 'medium' | 'high' | 'critical' | 'fatal' | 'other', required: Case severity values aligned with OCSF severity values. Values: UNKNOWN (0): The event/finding severity is unknown INFORMATIONAL (1): Informational message. No action required LOW (2): The user decides if action is needed MEDIUM (3): Action is required but the situation is not serious at this time HIGH (4): Action is required immediately CRITICAL (5): Action is required immediately and the scope is broad FATAL (6): An error occurred but it is too late to take remedial action OTHER (99): The event/finding severity is not mapped - `status` 'unknown' | 'new' | 'in_progress' | 'on_hold' | 'resolved' | 'closed' | 'other', required: Case status values aligned with OCSF Incident Finding status. - WorkflowArtifact: Workflow artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'workflow' - `color` string, required - `isPublished` boolean, nullable - RunArtifact: Workflow run artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'run' - `workflowId` string, required - `status` 'running' | 'success' | 'failed' | 'cancelled', required - `startedAt` string, date-time, required - TableArtifact: Table artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'table' - `rowCount` integer, nullable - AgentArtifact: Agent preset artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'agent' - FormArtifact: Workflow form artifact. Lets a surface refresh a form the chat edited. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'form' - `status` 'online' | 'offline', nullable - AlertArtifact: Alert artifact stub. Extend when alert surfaces are wired. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'alert' - IntegrationArtifact: Integration artifact stub. Extend when integration surfaces are wired. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'integration' - SecretArtifact: Secret artifact stub. Extend when secret surfaces are wired. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'secret' - GenericArtifact: Escape hatch for surfaced objects without a dedicated panel view. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'generic' - `data` object, nullable - `parent_session_id` string, uuid, nullable - `spawned_by_session_id` string, uuid, nullable - `forked_from_session_id` string, uuid, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `messages` unknown[]: Session messages - unknown - ChatRead: Model for chat metadata with message history. - `id` string, uuid4, required: Unique chat identifier - `title` string, required: Human-readable title for the chat - `user_id` string, uuid4, required: ID of the user who owns the chat - `entity_type` 'case' | 'agent_preset' | 'agent_preset_builder' | 'copilot' | 'workflow' | 'approval' | 'external_channel', required: The type of entity associated with an agent session. Determines the context and behavior of the session: - CASE: Chat attached to a Case entity for investigation - AGENT_PRESET: Live chat testing a preset configuration - AGENT_PRESET_BUILDER: Builder chat for editing/configuring a preset - WORKSPACE_CHAT: Workspace-level chat assistant (wire value: copilot) - WORKFLOW: Workflow-initiated agent run (from action) - APPROVAL: Inbox approval continuation (hidden from main chat list) - EXTERNAL_CHANNEL: External channel session (e.g. Slack thread) - `entity_id` string, uuid4, required: ID of the associated entity - `tools` string[], required: Tools available to the agent - `mcp_integrations` string[]: MCP integration IDs attached to this chat - `agent_preset_id` string, uuid, nullable: Agent preset used for this chat, if any - `agent_preset_version_id` string, uuid, nullable: Pinned preset version used for this chat, if any - `created_at` string, date-time, required: When the chat was created - `updated_at` string, date-time, required: When the chat was last updated - `last_stream_id` string, nullable: Last processed Redis stream ID for this chat - `is_readonly` boolean: Whether this chat is read-only (legacy chats cannot be modified) - `messages` ChatMessage[]: Chat messages from Redis stream - `id` string, required: Unique message identifier - `kind` 'chat-message' | 'approval-request' | 'approval-decision' | 'internal' | 'compaction' | 'cancelled': The type/kind of message stored in the chat. - `message` union: The deserialized message (for kind=CHAT_MESSAGE) - UserMessage - `content` union, required - string - union[] - … - `uuid` string, nullable - `parent_tool_use_id` string, nullable - `tool_use_result` object, nullable - `origin` MessageOrigin - `kind` 'human' | 'channel' | 'peer' | 'task-notification' | 'coordinator' | 'unclassified' | 'observer' | 'auto-continuation' | 'observer-activity', required - `server` string - `from` string - `name` string - `fromSession` string - `senderTaskId` string - `body` string - `verifiedPeerPid` integer - `subkind` 'scheduled-trigger' | 'peer-send-message' - AssistantMessage - `content` union[], required - union - … - `model` string, required - `parent_tool_use_id` string, nullable - `error` 'authentication_failed' | 'billing_error' | 'rate_limit' | 'invalid_request' | 'server_error' | 'unknown', nullable - `usage` object, nullable - `message_id` string, nullable - `stop_reason` string, nullable - `session_id` string, nullable - `uuid` string, nullable - SystemMessage - `subtype` string, required - `data` object, required - ResultMessage - `subtype` string, required - `duration_ms` integer, required - `duration_api_ms` integer, required - `is_error` boolean, required - `num_turns` integer, required - `session_id` string, required - `stop_reason` string, nullable - `total_cost_usd` number, nullable - `usage` object, nullable - `result` string, nullable - `structured_output` unknown - `model_usage` object, nullable - `permission_denials` unknown[], nullable - unknown - `deferred_tool_use` DeferredToolUse - `id` string, required - `name` string, required - `input` object, required - `errors` string[], nullable - `api_error_status` integer, nullable - `uuid` string, nullable - `terminal_reason` string, nullable - `origin` MessageOrigin - `kind` 'human' | 'channel' | 'peer' | 'task-notification' | 'coordinator' | 'unclassified' | 'observer' | 'auto-continuation' | 'observer-activity', required - `server` string - `from` string - `name` string - `fromSession` string - `senderTaskId` string - `body` string - `verifiedPeerPid` integer - `subkind` 'scheduled-trigger' | 'peer-send-message' - StreamEvent - `uuid` string, required - `session_id` string, required - `event` object, required - `parent_tool_use_id` string, nullable - RateLimitEvent - `rate_limit_info` RateLimitInfo, required - `status` 'allowed' | 'allowed_warning' | 'rejected', required - `resets_at` integer, nullable - `rate_limit_type` 'five_hour' | 'seven_day' | 'seven_day_opus' | 'seven_day_sonnet' | 'overage', nullable - `utilization` number, nullable - `overage_status` 'allowed' | 'allowed_warning' | 'rejected', nullable - `overage_resets_at` integer, nullable - `overage_disabled_reason` string, nullable - `raw` object - `uuid` string, required - `session_id` string, required - ConversationResetMessage - `new_conversation_id` string, required - `uuid` string, required - `session_id` string, required - `approval` ApprovalRead: Response schema for approval data in chat timeline. - `id` string, uuid, required - `tool_call_id` string, required - `tool_name` string, required - `tool_call_args` object, nullable - `status` 'pending' | 'approved' | 'rejected', required: Possible states for a deferred tool approval. - `reason` string, nullable - `decision` union - boolean - ToolApprovedDecision: Persisted decision for a tool approved with argument overrides. - `kind` 'tool-approved', required - `override_args` object - `metadata` object - ToolDeniedDecision: Persisted decision for a denied tool call. - `kind` 'tool-denied', required - `message` string - `metadata` object - BooleanApprovalDecision: Persisted boolean decision enriched with submission metadata. - `value` boolean, required - `metadata` object, required - `approved_by` string, uuid, nullable - `approved_at` string, date-time, nullable - `created_at` string, date-time, required - `compaction` object, nullable: Compaction status data for badge rendering (for kind=COMPACTION) - `cancelled` object, nullable: Turn-cancelled marker data (for kind=CANCELLED) - `created_at` string, date-time, nullable: When the agent runtime recorded the message ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/tracecat/apis/tracecat-api.md) - [All operations](https://skmtc.dev/tracecat/apis/tracecat-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tracecat/apis/tracecat-api/revisions/2efdda25045f?raw)