Stream chat state

Real-time streaming conversation with Cube’s AI agents for analytics and data exploration.

The response is streamed as newline-delimited JSON (each line is a standalone JSON object terminated by \n) and served with Content-Type: application/json. Each line represents a chat message, a state update, or an error object. Assistant content arrives incrementally — updates to a previously emitted message carry the same id with isDelta: true.

Provide input to send a new message. Omit input (with a chatId) to retrieve the current thread state. If chatId is omitted a new thread is created and its id is returned on the __cutoff__ message.

Special sentinel messages:

• __cutoff__ — initial marker emitted before new content; also carries the thread chatId and isStreaming under state.
• __state__ — final thread snapshot emitted at the end, carrying the full { messages: [...] } state.

Errors mid-stream are emitted as a standalone line { "error": "<message>" } rather than a non-200 status.

Finding the final answer: filter assistant messages where graphPath[0] === "final" and graphPath.length <= 2; the last such message is the final answer.

Idempotency: provide a client-generated messageId in the format <timestamp>-message (a 13+ digit Unix-millisecond timestamp). If a request with the same messageId arrives while a stream for that message is still active on the thread, the API resubscribes the new request to the existing stream instead of starting a new one.

POST /chat/stream-chat-state

Stream chat state

cURL

curl --request POST \
  --url https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "activeBranchName": "<string>",
  "chatId": "<string>",
  "images": [
    {
      "data": "<string>",
      "mimeType": "<string>",
      "name": "<string>"
    }
  ],
  "input": "<string>",
  "isDefaultBranch": true,
  "messageId": "<string>",
  "sessionSettings": {
    "email": "<string>",
    "externalId": "<string>",
    "groups": [
      "<string>"
    ],
    "internalId": "<string>",
    "publicDashboardId": "<string>",
    "roles": [
      "<string>"
    ],
    "securityContext": {},
    "userAttributes": [
      "<unknown>"
    ]
  }
}
'

200

assistantDelta

{ "content": "", "graphPath": [ "cube_data_analyst_agent" ], "id": "cdfe1a84-08d7-40b9-8b1c-e7e3a698647e", "isDelta": true, "isInProcess": true, "role": "assistant", "sort": 2 }

Authorizations

apiKeycubeToken

Authorization · string · header · required

API key authentication. Send Authorization: Api-Key <YOUR_API_KEY>.

Body

application/json

Chat request. Provide input to send a new message, or omit it together with a chatId to retrieve the current thread state.

activeBranchName · string

Development branch name to run queries against. Uses the main branch if omitted.

chatId · string

Chat thread ID. If omitted, a new thread is created automatically. Should match the previously returned chatId carried on the __cutoff__ message.

images · object[]

Show child attributes

input · string

User's message/question. If omitted, returns the current thread state for the provided chatId.

isDefaultBranch · boolean

Whether activeBranchName is the default branch. Defaults to true when not set.

messageId · string

Client-provided identifier in the format <timestamp>-message (13+ digit Unix milliseconds). Makes requests idempotent.

Pattern: ^\d{13,}-message$

sessionSettings · object

Show child attributes

Response

200

application/json

Newline-delimited stream of chat message / state / error objects (served as Content-Type: application/json). Each line is a JSON object of the schema below.

content · string

Message content. Streamed incrementally for assistant messages when isDelta is true.

error · string

Present only on error lines ({ "error": "<message>" }). When set, the line carries no message fields.

graphPath · string[]

Agent graph node path, e.g. ["cube_data_analyst_agent"] or ["final"].

id · string

Unique message identifier. Sentinel values: __cutoff__ (initial marker, carries the chatId under state) and __state__ (final thread state snapshot). Absent on error lines.

isDelta · boolean

Whether this is an incremental update to a previously sent message with the same id.

isInProcess · boolean

Whether the message is still being generated.

role · enum<string>

Available options: user, assistant

sort · number

Message ordering sequence.

state · object

Streaming state. Carries { isStreaming, chatId } on the __cutoff__ message and { messages: [...] } on the __state__ message.

thinking · string

Agent's internal reasoning. Only present in development mode.

toolCall · object

Present when the message represents a tool invocation or its result.

Show child attributes