---
title: "Stream chat events via WebSockets"
method: GET
path: "/api/experimental/chats/{chat}/stream"
tags: ["Chats"]
---

# Stream chat events via WebSockets

`GET /api/experimental/chats/{chat}/stream`

Experimental: this endpoint is subject to change.

## Path parameters

- `chat` string, uuid, required

## Response `200`

OK

- CodersdkChatStreamEvent
  - `action_required` CodersdkChatStreamActionRequired
    - `tool_calls` CodersdkChatStreamToolCall[]
      - `args` string
      - `tool_call_id` string
      - `tool_name` string
  - `chat_id` string, uuid
  - `error` CodersdkChatError
    - `detail` string — Detail is optional provider-specific context shown alongside the normalized error message when available.
    - `kind` 'generic' | 'overloaded' | 'rate_limit' | 'timeout' | 'stream_silence_timeout' | 'auth' | 'config' | 'usage_limit' | 'missing_key' | 'provider_disabled' | 'content_filter' | 'hook_dispatch_failed' | 'hook_denied'
    - `message` string — Message is the normalized, user-facing error message.
    - `provider` string — Provider identifies the upstream model provider when known.
    - `retryable` boolean — Retryable reports whether the underlying error is transient.
    - `status_code` integer — StatusCode is the best-effort upstream HTTP status code.
  - `message` CodersdkChatMessage
    - `chat_id` string, uuid
    - `content` CodersdkChatMessagePart[]
      - `args` integer[]
      - `args_delta` string
      - `completed_at` string, date-time — CompletedAt is the time a reasoning part finished streaming, so reasoning duration can be computed as completed_at minus created_at. For interrupted reasoning, this is the interruption time. Absent when reasoning timestamp data was not recorded (e.g. messages persisted before this feature was added).
      - `content` string — The code content from the diff that was commented on.
      - `context_file_agent_id` UuidNullUUID
        - `uuid` string
        - `valid` boolean — Valid is true if UUID is not NULL
      - `context_file_content` string — ContextFileContent holds the file content sent to the LLM. Internal only: stripped before API responses to keep payloads small. The backend reads it when building the prompt via partsToMessageParts.
      - `context_file_directory` string — ContextFileDirectory is the working directory of the workspace agent. Internal only: same purpose as ContextFileOS.
      - `context_file_os` string — ContextFileOS is the operating system of the workspace agent. Internal only: used during prompt expansion so the LLM knows the OS even on turns where InsertSystem is not called.
      - `context_file_path` string — ContextFilePath is the absolute path of a file loaded into the LLM context (e.g. an AGENTS.md instruction file).
      - `context_file_skill_meta_file` string — ContextFileSkillMetaFile is the basename of the skill meta file (e.g. "SKILL.md") at the time of persistence. Internal only: restored on subsequent turns so the read_skill tool uses the correct filename even when the agent configured a non-default value.
      - `context_file_truncated` boolean — ContextFileTruncated indicates the file exceeded the 64KiB instruction file limit and was truncated.
      - `created_at` string, date-time — CreatedAt is the timestamp this part carries. The semantics depend on the part type: for tool-call and tool-result parts it is the time the call was emitted or the result was produced (tool duration is the result's created_at minus the call's created_at); for reasoning parts it is the time reasoning started streaming.
      - `data` integer[]
      - `end_line` integer
      - `file_id` UuidNullUUID
        - `uuid` string
        - `valid` boolean — Valid is true if UUID is not NULL
      - `file_name` string
      - `hook_rewritten` boolean — HookRewritten indicates that a lifecycle hook replaced model-proposed tool input.
      - `is_error` boolean
      - `is_media` boolean
      - `mcp_server_config_id` UuidNullUUID
        - `uuid` string
        - `valid` boolean — Valid is true if UUID is not NULL
      - `media_type` string
      - `name` string
      - `parsed_commands` array[] — ParsedCommands holds parsed programs from an execute tool call's shell command, one entry per simple command in source order. Each entry is [program] or [program, arg] where arg is the first non-flag positional argument. Program names are normalized to their base name (e.g. /usr/bin/go becomes go). Only populated when ToolName is "execute" and the command parses successfully; nil otherwise.
        - string[]
      - `provider_executed` boolean — ProviderExecuted indicates the tool call was executed by the provider (e.g. Anthropic computer use).
      - `provider_metadata` integer[] — ProviderMetadata holds provider-specific response metadata (e.g. Anthropic cache control hints) as raw JSON. Internal only: stripped by db2sdk before API responses.
      - `result` integer[]
      - `result_delta` string
      - `result_reset` boolean
      - `skill_description` string — SkillDescription is the short description from the skill's SKILL.md frontmatter.
      - `skill_dir` string — SkillDir is the absolute path to the skill directory inside the workspace filesystem. Internal only: used by read_skill/read_skill_file tools to locate skill files.
      - `skill_name` string — SkillName is the kebab-case name of a discovered skill from the workspace's .agents/skills/ directory.
      - `source_id` string
      - `start_line` integer
      - `text` string
      - `title` string
      - `tool_call_id` string
      - `tool_name` string
      - `type` 'text' | 'reasoning' | 'tool-call' | 'tool-result' | 'source' | 'file' | 'file-reference' | 'context-file' | 'skill' | 'hook-context' | 'hook-notice'
      - `url` string
    - `created_at` string, date-time
    - `created_by` string, uuid
    - `id` integer
    - `model_config_id` string, uuid
    - `role` 'system' | 'user' | 'assistant' | 'tool'
    - `usage` CodersdkChatMessageUsage
      - `cache_creation_tokens` integer
      - `cache_read_tokens` integer
      - `context_limit` integer
      - `input_tokens` integer
      - `output_tokens` integer
      - `reasoning_tokens` integer
      - `total_tokens` integer
  - `message_part` CodersdkChatStreamMessagePart
    - `generation_attempt` integer
    - `history_version` integer
    - `part` CodersdkChatMessagePart
      - `args` integer[]
      - `args_delta` string
      - `completed_at` string, date-time — CompletedAt is the time a reasoning part finished streaming, so reasoning duration can be computed as completed_at minus created_at. For interrupted reasoning, this is the interruption time. Absent when reasoning timestamp data was not recorded (e.g. messages persisted before this feature was added).
      - `content` string — The code content from the diff that was commented on.
      - `context_file_agent_id` UuidNullUUID
        - `uuid` string
        - `valid` boolean — Valid is true if UUID is not NULL
      - `context_file_content` string — ContextFileContent holds the file content sent to the LLM. Internal only: stripped before API responses to keep payloads small. The backend reads it when building the prompt via partsToMessageParts.
      - `context_file_directory` string — ContextFileDirectory is the working directory of the workspace agent. Internal only: same purpose as ContextFileOS.
      - `context_file_os` string — ContextFileOS is the operating system of the workspace agent. Internal only: used during prompt expansion so the LLM knows the OS even on turns where InsertSystem is not called.
      - `context_file_path` string — ContextFilePath is the absolute path of a file loaded into the LLM context (e.g. an AGENTS.md instruction file).
      - `context_file_skill_meta_file` string — ContextFileSkillMetaFile is the basename of the skill meta file (e.g. "SKILL.md") at the time of persistence. Internal only: restored on subsequent turns so the read_skill tool uses the correct filename even when the agent configured a non-default value.
      - `context_file_truncated` boolean — ContextFileTruncated indicates the file exceeded the 64KiB instruction file limit and was truncated.
      - `created_at` string, date-time — CreatedAt is the timestamp this part carries. The semantics depend on the part type: for tool-call and tool-result parts it is the time the call was emitted or the result was produced (tool duration is the result's created_at minus the call's created_at); for reasoning parts it is the time reasoning started streaming.
      - `data` integer[]
      - `end_line` integer
      - `file_id` UuidNullUUID
        - `uuid` string
        - `valid` boolean — Valid is true if UUID is not NULL
      - `file_name` string
      - `hook_rewritten` boolean — HookRewritten indicates that a lifecycle hook replaced model-proposed tool input.
      - `is_error` boolean
      - `is_media` boolean
      - `mcp_server_config_id` UuidNullUUID
        - `uuid` string
        - `valid` boolean — Valid is true if UUID is not NULL
      - `media_type` string
      - `name` string
      - `parsed_commands` array[] — ParsedCommands holds parsed programs from an execute tool call's shell command, one entry per simple command in source order. Each entry is [program] or [program, arg] where arg is the first non-flag positional argument. Program names are normalized to their base name (e.g. /usr/bin/go becomes go). Only populated when ToolName is "execute" and the command parses successfully; nil otherwise.
        - string[]
      - `provider_executed` boolean — ProviderExecuted indicates the tool call was executed by the provider (e.g. Anthropic computer use).
      - `provider_metadata` integer[] — ProviderMetadata holds provider-specific response metadata (e.g. Anthropic cache control hints) as raw JSON. Internal only: stripped by db2sdk before API responses.
      - `result` integer[]
      - `result_delta` string
      - `result_reset` boolean
      - `skill_description` string — SkillDescription is the short description from the skill's SKILL.md frontmatter.
      - `skill_dir` string — SkillDir is the absolute path to the skill directory inside the workspace filesystem. Internal only: used by read_skill/read_skill_file tools to locate skill files.
      - `skill_name` string — SkillName is the kebab-case name of a discovered skill from the workspace's .agents/skills/ directory.
      - `source_id` string
      - `start_line` integer
      - `text` string
      - `title` string
      - `tool_call_id` string
      - `tool_name` string
      - `type` 'text' | 'reasoning' | 'tool-call' | 'tool-result' | 'source' | 'file' | 'file-reference' | 'context-file' | 'skill' | 'hook-context' | 'hook-notice'
      - `url` string
    - `role` 'system' | 'user' | 'assistant' | 'tool'
    - `seq` integer
  - `queued_messages` CodersdkChatQueuedMessage[]
    - `chat_id` string, uuid
    - `content` CodersdkChatMessagePart[]
      - `args` integer[]
      - `args_delta` string
      - `completed_at` string, date-time — CompletedAt is the time a reasoning part finished streaming, so reasoning duration can be computed as completed_at minus created_at. For interrupted reasoning, this is the interruption time. Absent when reasoning timestamp data was not recorded (e.g. messages persisted before this feature was added).
      - `content` string — The code content from the diff that was commented on.
      - `context_file_agent_id` UuidNullUUID
        - `uuid` string
        - `valid` boolean — Valid is true if UUID is not NULL
      - `context_file_content` string — ContextFileContent holds the file content sent to the LLM. Internal only: stripped before API responses to keep payloads small. The backend reads it when building the prompt via partsToMessageParts.
      - `context_file_directory` string — ContextFileDirectory is the working directory of the workspace agent. Internal only: same purpose as ContextFileOS.
      - `context_file_os` string — ContextFileOS is the operating system of the workspace agent. Internal only: used during prompt expansion so the LLM knows the OS even on turns where InsertSystem is not called.
      - `context_file_path` string — ContextFilePath is the absolute path of a file loaded into the LLM context (e.g. an AGENTS.md instruction file).
      - `context_file_skill_meta_file` string — ContextFileSkillMetaFile is the basename of the skill meta file (e.g. "SKILL.md") at the time of persistence. Internal only: restored on subsequent turns so the read_skill tool uses the correct filename even when the agent configured a non-default value.
      - `context_file_truncated` boolean — ContextFileTruncated indicates the file exceeded the 64KiB instruction file limit and was truncated.
      - `created_at` string, date-time — CreatedAt is the timestamp this part carries. The semantics depend on the part type: for tool-call and tool-result parts it is the time the call was emitted or the result was produced (tool duration is the result's created_at minus the call's created_at); for reasoning parts it is the time reasoning started streaming.
      - `data` integer[]
      - `end_line` integer
      - `file_id` UuidNullUUID
        - `uuid` string
        - `valid` boolean — Valid is true if UUID is not NULL
      - `file_name` string
      - `hook_rewritten` boolean — HookRewritten indicates that a lifecycle hook replaced model-proposed tool input.
      - `is_error` boolean
      - `is_media` boolean
      - `mcp_server_config_id` UuidNullUUID
        - `uuid` string
        - `valid` boolean — Valid is true if UUID is not NULL
      - `media_type` string
      - `name` string
      - `parsed_commands` array[] — ParsedCommands holds parsed programs from an execute tool call's shell command, one entry per simple command in source order. Each entry is [program] or [program, arg] where arg is the first non-flag positional argument. Program names are normalized to their base name (e.g. /usr/bin/go becomes go). Only populated when ToolName is "execute" and the command parses successfully; nil otherwise.
        - string[]
      - `provider_executed` boolean — ProviderExecuted indicates the tool call was executed by the provider (e.g. Anthropic computer use).
      - `provider_metadata` integer[] — ProviderMetadata holds provider-specific response metadata (e.g. Anthropic cache control hints) as raw JSON. Internal only: stripped by db2sdk before API responses.
      - `result` integer[]
      - `result_delta` string
      - `result_reset` boolean
      - `skill_description` string — SkillDescription is the short description from the skill's SKILL.md frontmatter.
      - `skill_dir` string — SkillDir is the absolute path to the skill directory inside the workspace filesystem. Internal only: used by read_skill/read_skill_file tools to locate skill files.
      - `skill_name` string — SkillName is the kebab-case name of a discovered skill from the workspace's .agents/skills/ directory.
      - `source_id` string
      - `start_line` integer
      - `text` string
      - `title` string
      - `tool_call_id` string
      - `tool_name` string
      - `type` 'text' | 'reasoning' | 'tool-call' | 'tool-result' | 'source' | 'file' | 'file-reference' | 'context-file' | 'skill' | 'hook-context' | 'hook-notice'
      - `url` string
    - `created_at` string, date-time
    - `id` integer
    - `model_config_id` string, uuid
  - `retry` CodersdkChatStreamRetry
    - `attempt` integer — Attempt is the 1-indexed retry attempt number.
    - `delay_ms` integer — DelayMs is the backoff delay in milliseconds before the retry.
    - `error` string — Error is the normalized error message from the failed attempt.
    - `kind` 'generic' | 'overloaded' | 'rate_limit' | 'timeout' | 'stream_silence_timeout' | 'auth' | 'config' | 'usage_limit' | 'missing_key' | 'provider_disabled' | 'content_filter' | 'hook_dispatch_failed' | 'hook_denied'
    - `provider` string — Provider identifies the upstream model provider when known.
    - `retrying_at` string, date-time — RetryingAt is the timestamp when the retry will be attempted.
    - `status_code` integer — StatusCode is the best-effort upstream HTTP status code.
  - `status` CodersdkChatStreamStatus
    - `status` 'waiting' | 'running' | 'error' | 'requires_action' | 'interrupting'
  - `type` 'message_part' | 'message' | 'status' | 'error' | 'queue_update' | 'retry' | 'action_required' | 'preview_reset' | 'history_reset'

---

[API](https://skmtc.net/coder/apis/coder-api.md) · [All operations](https://skmtc.net/coder/apis/coder-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/coder/coder-api/versions/56b6e9f08540/schema)