> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cerca.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Thread message stream

> Server-Sent Events stream. Each SSE data frame is JSON matching this response schema.



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/cerca/openapi.documented.yml get /agents/{agentId}/threads/{threadId}/stream
openapi: 3.1.0
info:
  description: API-key accessible routes for Cerca agents.
  title: Cerca API
  version: 0.0.0
servers:
  - url: https://api.cerca.dev
security:
  - bearerAuth: []
paths:
  /agents/{agentId}/threads/{threadId}/stream:
    get:
      tags:
        - Events
      summary: Thread message stream
      description: >-
        Server-Sent Events stream. Each SSE data frame is JSON matching this
        response schema.
      parameters:
        - schema:
            type: string
            minLength: 1
            example: agent_abc123
          required: true
          in: path
          name: agentId
        - schema:
            type: string
            minLength: 1
            example: thread_abc123
          required: true
          in: path
          name: threadId
      responses:
        '200':
          description: Thread message stream
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ThreadStreamMessage'
        '400':
          description: Invalid runtime request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Access denied or non-transient quota exceeded. Limit errors include
            a stable code field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Runtime resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: >-
            Transient capacity limit exceeded. Limit errors include a stable
            code field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Required runtime dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Runtime error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Cerca from '@cerca-dev/sdk';


            const client = new Cerca({
              apiKey: process.env['CERCA_API_KEY'], // This is the default and can be omitted
            });


            const threadStreamEvent = await
            client.events.streamForThread('agent_abc123', 'thread_abc123');


            console.log(threadStreamEvent);
        - lang: Python
          source: |-
            import os
            from cerca import Cerca

            client = Cerca(
                api_key=os.environ.get("CERCA_API_KEY"),  # This is the default and can be omitted
            )
            for event in client.events.stream_for_thread(
                agent_id="agent_abc123",
                thread_id="thread_abc123",
            ):
              print(event)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/matrices/cerca-go\"\n\t\"github.com/matrices/cerca-go/option\"\n)\n\nfunc main() {\n\tclient := cercago.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tstream := client.Events.StreamForThreadStreaming(\n\t\tcontext.TODO(),\n\t\t\"agent_abc123\",\n\t\t\"thread_abc123\",\n\t)\n\tfor stream.Next() {\n\t\tfmt.Printf(\"%+v\\n\", stream.Current())\n\t}\n\terr := stream.Err()\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
        - lang: Ruby
          source: >-
            require "cerca"


            cerca = Cerca::Client.new(api_key: "My API Key")


            thread_stream_event = cerca.events.stream_for_thread("agent_abc123",
            "thread_abc123")


            puts(thread_stream_event)
        - lang: CLI
          source: |-
            cerca events stream-for-thread \
              --api-key 'My API Key' \
              --agent-id agent_abc123 \
              --thread-id thread_abc123
components:
  schemas:
    ThreadStreamMessage:
      oneOf:
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            error:
              type:
                - string
                - 'null'
            result:
              type:
                - string
                - 'null'
            status:
              $ref: '#/components/schemas/ThreadStatus'
            stepSeq:
              type: number
            type:
              type: string
              enum:
                - status
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - error
            - result
            - status
            - stepSeq
            - type
          title: ThreadStreamStatusMessage
          x-stainless-variantName: ThreadStreamStatusMessage
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            message:
              $ref: '#/components/schemas/ThreadStreamThreadMessage'
            stepSeq:
              type: number
            type:
              type: string
              enum:
                - message
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - message
            - stepSeq
            - type
          title: ThreadStreamContentMessage
          x-stainless-variantName: ThreadStreamContentMessage
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            messageCount:
              type: number
            stepCount:
              type: number
            stepSeq:
              type: number
            type:
              type: string
              enum:
                - progress
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - messageCount
            - stepCount
            - stepSeq
            - type
          title: ThreadStreamProgressMessage
          x-stainless-variantName: ThreadStreamProgressMessage
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            turnSeq:
              type: number
            type:
              type: string
              enum:
                - turn/started
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - turnSeq
            - type
          title: ThreadStreamTurnStartedMessage
          x-stainless-variantName: ThreadStreamTurnStartedMessage
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            error:
              type:
                - string
                - 'null'
            result:
              type:
                - string
                - 'null'
            status:
              type: string
              enum:
                - completed
                - failed
            turnSeq:
              type: number
            type:
              type: string
              enum:
                - turn/completed
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - error
            - result
            - status
            - turnSeq
            - type
          title: ThreadStreamTurnCompletedMessage
          x-stainless-variantName: ThreadStreamTurnCompletedMessage
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            itemId:
              type: string
            itemType:
              $ref: '#/components/schemas/ThreadStreamItemType'
            requestedToolName:
              type: string
            subThreadId:
              type: string
            toolName:
              $ref: '#/components/schemas/RuntimeToolName'
            type:
              type: string
              enum:
                - item/started
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - itemId
            - itemType
            - type
          title: ThreadStreamItemStartedMessage
          x-stainless-variantName: ThreadStreamItemStartedMessage
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            durationMs:
              type: number
            isError:
              type: boolean
            itemId:
              type: string
            itemType:
              $ref: '#/components/schemas/ThreadStreamItemType'
            requestedToolName:
              type: string
            type:
              type: string
              enum:
                - item/completed
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - durationMs
            - itemId
            - itemType
            - type
          title: ThreadStreamItemCompletedMessage
          x-stainless-variantName: ThreadStreamItemCompletedMessage
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            cumulativeInputTokens:
              type: number
            cumulativeOutputTokens:
              type: number
            inputTokens:
              type: number
            outputTokens:
              type: number
            type:
              type: string
              enum:
                - token_usage
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - cumulativeInputTokens
            - cumulativeOutputTokens
            - inputTokens
            - outputTokens
            - type
          title: ThreadStreamTokenUsageMessage
          x-stainless-variantName: ThreadStreamTokenUsageMessage
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            approval:
              $ref: '#/components/schemas/ThreadStreamApprovalRequest'
            type:
              type: string
              enum:
                - approval/requested
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - approval
            - type
          title: ThreadStreamApprovalRequestedMessage
          x-stainless-variantName: ThreadStreamApprovalRequestedMessage
        - type: object
          properties:
            eventSeq:
              type: number
            turnId:
              type: string
            approvalId:
              type: string
            decision:
              type: string
              enum:
                - approve
                - deny
                - cancel
                - timeout
            type:
              type: string
              enum:
                - approval/resolved
              x-stainless-const: true
          required:
            - eventSeq
            - turnId
            - approvalId
            - decision
            - type
          title: ThreadStreamApprovalResolvedMessage
          x-stainless-variantName: ThreadStreamApprovalResolvedMessage
      discriminator:
        propertyName: type
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          description: Stable machine-readable error code when the API can provide one.
          example: MONTHLY_TOKEN_BUDGET_EXCEEDED
      required:
        - error
    ThreadStatus:
      type: string
      enum:
        - idle
        - running
        - awaiting
        - closed
      description: >-
        `idle` threads can accept a new turn or be closed. `running` threads
        have an active turn. `awaiting` threads are paused on external input
        such as approvals. `closed` threads are terminal.
    ThreadStreamThreadMessage:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/ThreadStreamContentBlock'
        createdAt:
          type: string
        role:
          type: string
          enum:
            - user
            - assistant
        seq:
          type: number
      required:
        - content
        - createdAt
        - role
        - seq
    ThreadStreamItemType:
      type: string
      enum:
        - tool_call
        - agent_message
        - llm_call
        - sub_thread
    RuntimeToolName:
      type: string
      enum:
        - get_time
        - sub_thread
        - wait
        - tool.call
        - tool.discover
        - artifact.read
        - agent.threads.list
        - agent.threads.get
        - agent.approvals.cancel
        - agent.approvals.grant_thread
        - agent.approvals.grant_agent
        - agent.create
        - agent.approvals.update
        - tool.connect
        - sandbox.exec
        - sandbox.read
        - sandbox.write_file
        - sandbox.read_file
        - sandbox.spawn
        - sandbox.stdin
        - sandbox.session_read
        - sandbox.kill
        - sandbox.list_sessions
        - sandbox.sync_artifact
        - memory.read
        - memory.list
        - memory.search
        - memory.write
        - memory.delete
        - db.query
        - web.search
        - web.fetch
        - agent.schedule.list
        - agent.schedule.create
        - agent.schedule.update
        - agent.schedule.delete
        - agent.schedule.trigger
    ThreadStreamApprovalRequest:
      type: object
      properties:
        createdAt:
          type: string
        id:
          type: string
        requestedToolName:
          type: string
        resolvedAt:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - approved
            - denied
            - cancelled
            - timed_out
        threadId:
          type: string
        timeoutAt:
          type:
            - string
            - 'null'
        timeoutMs:
          type:
            - number
            - 'null'
        toolIndex:
          type: number
        toolInput:
          $ref: '#/components/schemas/SerializedToolInput'
        toolName:
          $ref: '#/components/schemas/RuntimeToolName'
        toolSourceId:
          type: string
        toolSourceVersion:
          type: number
        toolUseId:
          type: string
        turnId:
          type: string
      required:
        - createdAt
        - id
        - requestedToolName
        - resolvedAt
        - status
        - threadId
        - timeoutAt
        - timeoutMs
        - toolIndex
        - toolInput
        - toolName
        - toolUseId
        - turnId
    ThreadStreamContentBlock:
      oneOf:
        - $ref: '#/components/schemas/ThreadStreamTextContentBlock'
        - $ref: '#/components/schemas/ThreadStreamToolUseContentBlock'
        - $ref: '#/components/schemas/ThreadStreamToolResultContentBlock'
        - $ref: '#/components/schemas/ThreadStreamServerToolUseContentBlock'
        - $ref: '#/components/schemas/ThreadStreamWebSearchToolResultContentBlock'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/ThreadStreamTextContentBlock'
          tool_use:
            $ref: '#/components/schemas/ThreadStreamToolUseContentBlock'
          tool_result:
            $ref: '#/components/schemas/ThreadStreamToolResultContentBlock'
          server_tool_use:
            $ref: '#/components/schemas/ThreadStreamServerToolUseContentBlock'
          web_search_tool_result:
            $ref: '#/components/schemas/ThreadStreamWebSearchToolResultContentBlock'
    SerializedToolInput:
      type: string
      description: >-
        JSON-serialized tool input payload. Parse as JSON before reading
        tool-specific fields.
    ThreadStreamTextContentBlock:
      type: object
      properties:
        providerMetadata:
          $ref: '#/components/schemas/ThreadStreamProviderMetadata'
        text:
          type: string
        type:
          type: string
          enum:
            - text
          x-stainless-const: true
      required:
        - text
        - type
    ThreadStreamToolUseContentBlock:
      type: object
      properties:
        id:
          type: string
        input:
          $ref: '#/components/schemas/SerializedToolInput'
        name:
          $ref: '#/components/schemas/RuntimeToolName'
        providerMetadata:
          $ref: '#/components/schemas/ThreadStreamProviderMetadata'
        type:
          type: string
          enum:
            - tool_use
          x-stainless-const: true
      required:
        - id
        - input
        - name
        - type
    ThreadStreamToolResultContentBlock:
      type: object
      properties:
        content:
          type: string
        deniedByUser:
          type: boolean
        isError:
          type: boolean
        providerMetadata:
          $ref: '#/components/schemas/ThreadStreamProviderMetadata'
        toolUseId:
          type: string
        type:
          type: string
          enum:
            - tool_result
          x-stainless-const: true
      required:
        - content
        - isError
        - toolUseId
        - type
    ThreadStreamServerToolUseContentBlock:
      type: object
      properties:
        id:
          type: string
        input:
          $ref: '#/components/schemas/SerializedToolInput'
        name:
          type: string
        providerMetadata:
          $ref: '#/components/schemas/ThreadStreamProviderMetadata'
        type:
          type: string
          enum:
            - server_tool_use
          x-stainless-const: true
      required:
        - id
        - input
        - name
        - type
    ThreadStreamWebSearchToolResultContentBlock:
      type: object
      properties:
        content:
          x-stainless-any: true
          description: >-
            Web search result payload. The runtime returns either an array of
            web search results or an error object.
        toolUseId:
          type: string
        type:
          type: string
          enum:
            - web_search_tool_result
          x-stainless-const: true
      required:
        - content
        - toolUseId
        - type
    ThreadStreamProviderMetadata:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/ThreadStreamProviderMetadataEntry'
    ThreadStreamProviderMetadataEntry:
      type: object
      additionalProperties:
        type: string
  securitySchemes:
    bearerAuth:
      bearerFormat: Cerca API key
      scheme: bearer
      type: http

````