Stream chat state

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>",
  "agentId": 123,
  "chatId": "<string>",
  "cubeCredentials": "<unknown>",
  "images": [
    {
      "data": "<string>",
      "mimeType": "<string>",
      "name": "<string>"
    }
  ],
  "input": "<string>",
  "isDefaultBranch": true,
  "isDevMode": true,
  "messageId": "<string>",
  "sessionSettings": {
    "email": "<string>",
    "externalId": "<string>",
    "groups": [
      "<string>"
    ],
    "internalId": "<string>",
    "publicDashboardId": "<string>",
    "roles": [
      "<string>"
    ],
    "securityContext": {},
    "userAttributes": [
      "<unknown>"
    ]
  },
  "workbookContext": {
    "charts": [
      {
        "sql": "<string>",
        "widgetId": "<string>",
        "baseSql": "<string>",
        "logicalFilters": "<unknown>",
        "reportId": 123,
        "title": "<string>"
      }
    ],
    "filters": [
      {
        "semanticView": "<string>",
        "widgetId": "<string>",
        "filter": {}
      }
    ]
  },
  "workbookId": 123
}
'

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

AI Endpoints

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 --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>",
  "agentId": 123,
  "chatId": "<string>",
  "cubeCredentials": "<unknown>",
  "images": [
    {
      "data": "<string>",
      "mimeType": "<string>",
      "name": "<string>"
    }
  ],
  "input": "<string>",
  "isDefaultBranch": true,
  "isDevMode": true,
  "messageId": "<string>",
  "sessionSettings": {
    "email": "<string>",
    "externalId": "<string>",
    "groups": [
      "<string>"
    ],
    "internalId": "<string>",
    "publicDashboardId": "<string>",
    "roles": [
      "<string>"
    ],
    "securityContext": {},
    "userAttributes": [
      "<unknown>"
    ]
  },
  "workbookContext": {
    "charts": [
      {
        "sql": "<string>",
        "widgetId": "<string>",
        "baseSql": "<string>",
        "logicalFilters": "<unknown>",
        "reportId": 123,
        "title": "<string>"
      }
    ],
    "filters": [
      {
        "semanticView": "<string>",
        "widgetId": "<string>",
        "filter": {}
      }
    ]
  },
  "workbookId": 123
}
'

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

Authorizations

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.

agentId

number | null

chatId

string

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

context

enum<string>

Available options:

chat,

workbook,

model,

dashboard,

external,

mcp,

ai-widget,

onboarding,

explore,

connection_setup,

slack_dm,

published-dashboard

cubeCredentials

any

dashboardContext

object

Show child attributes

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.

isDevMode

boolean

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

workbookContext

object

Show child attributes

workbookId

number

Response

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"].

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

Load Metadata Get deployments

⌘I