---
title: "Stream Task Events by Name"
method: GET
path: "/tasks/name/{task_name}/stream"
tags: ["Tasks"]
---

# Stream Task Events by Name

`GET /tasks/name/{task_name}/stream`

Stream events for a task by its unique name using Server-Sent Events (SSE).

    Supports automatic reconnection with Last-Event-ID header. When the client
    reconnects, it sends the Last-Event-ID header with the last received event ID,
    and the server resumes from that point.

    Returns TextStreamPart events (Vercel AI SDK compatible format).

## Path parameters

- `task_name` string, required

## Query parameters

- `agent_id` string, nullable — Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.

## Response `200`

SSE stream of TextStreamPart events

- union — Wrapper for TextStreamPart union for proper serialization.
  - StartPart — Marks the start of a streaming session.
    - `type` 'start'
  - StartStepPart — Marks the start of a new step (API call).
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `request` object, nullable — Request details for this step
    - `type` 'start-step'
    - `warnings` unknown[], nullable — Warnings from this step
      - unknown
  - FinishStepPart — Marks the end of a step (API call).
    - `finishReason` 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'error' | 'other', required — Reason for stream completion.
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `type` 'finish-step'
    - `usage` StreamUsage, required — Token usage for streaming events.
      - `inputTokens` integer, required — Input tokens used
      - `outputTokens` integer, required — Output tokens used
      - `totalTokens` integer, nullable — Total tokens
  - FinishPart — Marks the end of the entire streaming session.
    - `finishReason` 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'error' | 'other', required — Reason for stream completion.
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `totalUsage` StreamUsage, required — Token usage for streaming events.
      - `inputTokens` integer, required — Input tokens used
      - `outputTokens` integer, required — Output tokens used
      - `totalTokens` integer, nullable — Total tokens
    - `type` 'finish'
  - HandlerCompletePart — Marks completion of event/send handler lifecycle for a specific event.
    - `durationMs` integer, nullable — Handler runtime in milliseconds
    - `error` string, nullable — Handler error text when execution failed
    - `eventId` string, required — Event ID correlated to this handler completion
    - `success` boolean, required — Whether handler execution succeeded
    - `taskId` string, required — Task ID whose handler lifecycle completed
    - `type` 'handler-complete'
  - TextStartPart — Marks the start of a text block.
    - `id` string, required — Unique ID for this text block
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `type` 'text-start'
  - TextDeltaPart — Incremental text content.
    - `id` string, required — ID of the text block this belongs to
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `text` string, required — Text delta content
    - `type` 'text-delta'
  - TextEndPart — Marks the end of a text block.
    - `id` string, required — ID of the completed text block
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `type` 'text-end'
  - ReasoningStartPart — Marks the start of a reasoning block.
    - `id` string, required — Unique ID for this reasoning block
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `type` 'reasoning-start'
  - ReasoningDeltaPart — Incremental reasoning content.
    - `id` string, required — ID of the reasoning block this belongs to
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `text` string, required — Reasoning delta content
    - `type` 'reasoning-delta'
  - ReasoningEndPart — Marks the end of a reasoning block.
    - `id` string, required — ID of the completed reasoning block
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `type` 'reasoning-end'
  - ToolInputStartPart — Marks the start of tool input streaming.
    - `id` string, required — Tool call ID (e.g., toolu_01XYZ)
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `toolName` string, required — Name of the tool
    - `type` 'tool-input-start'
  - ToolInputDeltaPart — Incremental tool input JSON.
    - `delta` string, required — Partial JSON input
    - `id` string, required — Tool call ID
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `type` 'tool-input-delta'
  - ToolInputEndPart — Marks the end of tool input streaming.
    - `id` string, required — Tool call ID
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `type` 'tool-input-end'
  - ToolCallPart — Complete tool call with parsed input.
    - `input` object, required — Parsed input arguments
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `toolCallId` string, required — Unique tool call ID
    - `toolName` string, required — Name of the tool
    - `type` 'tool-call'
  - ToolResultPart — Tool execution result.
    - `metadata` StreamMetadata — Extended metadata for finish events.
      - `cacheCreationInputTokens` integer, nullable — Cache creation input tokens
      - `cacheReadInputTokens` integer, nullable — Cache read input tokens
      - `costUsd` number, nullable — Total cost in USD
      - `durationMs` integer, nullable — Total duration in milliseconds
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
    - `output` unknown, required
    - `toolCallId` string, required — Tool call ID
    - `toolName` string, required — Name of the tool
    - `type` 'tool-result'
  - StreamErrorPart — Error during streaming.
    - `error` string, required — Error message
    - `rawContent` unknown
    - `type` 'error'

## Other responses

- `422` — Validation Error

---

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