--- title: "List Sessions" method: GET path: "/workspaces/{workspace_id}/agent/sessions" tags: ["agent-sessions"] --- # List Sessions `GET /workspaces/{workspace_id}/agent/sessions` ## Request - Base URL: `https://platform.tracecat.com/api` - URL: `https://platform.tracecat.com/api/workspaces/{workspace_id}/agent/sessions` - Auth: one of: - API key in cookie `fastapiusersauth` - HTTP bearer List agent sessions for the current workspace with optional filtering. Returns root sessions by default, including standalone history forks and legacy chats. Filter by spawned_by_session_id to find spawned children. Legacy chats have is_readonly=True. ## Path parameters - `workspace_id` string, uuid, required ## Query parameters - `entity_type` 'case' | 'agent_preset' | 'agent_preset_builder' | 'copilot' | 'workflow' | 'approval' | 'external_channel': 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, nullable: Filter by entity ID - `created_by` string, uuid, nullable: Filter by session creator. Omit to list the entire workspace. - `exclude_entity_types` AgentSessionEntity[], nullable: Entity types to exclude from results - `spawned_by_session_id` string, uuid, nullable: Filter by spawning parent session ID - `include_children` boolean: Include spawned children without a parent filter - `limit` integer: Maximum number of sessions to return - `forked_from_session_id` string, uuid, nullable: Filter by history source session ID - `parent_session_id` string, uuid, nullable: Legacy alias for forked_from_session_id ## Response `200` Successful Response - union[] - union - AgentSessionRead: Response schema for agent session. - `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. - … - `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. - … - `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. - … - `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. - … - `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. - … - `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. - … - `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. - … - `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. - … - `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. - … - `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. - … - `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 - ChatReadMinimal: Model for chat metadata without messages. Note: Legacy Chat records are read-only (is_readonly=True). - `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) ## Other responses - `400`: Conflicting parent_session_id and forked_from_session_id filters - `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)