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>",
  "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>"
    ]
  }
}
'

import requests

url = "https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state"

payload = {
    "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>"]
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>']
    }
  })
};

fetch('https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state"

	payload := strings.NewReader("{\n  \"activeBranchName\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"images\": [\n    {\n      \"data\": \"<string>\",\n      \"mimeType\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"input\": \"<string>\",\n  \"isDefaultBranch\": true,\n  \"messageId\": \"<string>\",\n  \"sessionSettings\": {\n    \"email\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"groups\": [\n      \"<string>\"\n    ],\n    \"internalId\": \"<string>\",\n    \"publicDashboardId\": \"<string>\",\n    \"roles\": [\n      \"<string>\"\n    ],\n    \"securityContext\": {},\n    \"userAttributes\": [\n      \"<unknown>\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"activeBranchName\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"images\": [\n    {\n      \"data\": \"<string>\",\n      \"mimeType\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"input\": \"<string>\",\n  \"isDefaultBranch\": true,\n  \"messageId\": \"<string>\",\n  \"sessionSettings\": {\n    \"email\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"groups\": [\n      \"<string>\"\n    ],\n    \"internalId\": \"<string>\",\n    \"publicDashboardId\": \"<string>\",\n    \"roles\": [\n      \"<string>\"\n    ],\n    \"securityContext\": {},\n    \"userAttributes\": [\n      \"<unknown>\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"activeBranchName\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"images\": [\n    {\n      \"data\": \"<string>\",\n      \"mimeType\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"input\": \"<string>\",\n  \"isDefaultBranch\": true,\n  \"messageId\": \"<string>\",\n  \"sessionSettings\": {\n    \"email\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"groups\": [\n      \"<string>\"\n    ],\n    \"internalId\": \"<string>\",\n    \"publicDashboardId\": \"<string>\",\n    \"roles\": [\n      \"<string>\"\n    ],\n    \"securityContext\": {},\n    \"userAttributes\": [\n      \"<unknown>\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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, a usage frame, 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__ — thread snapshot emitted near the end, carrying the full { messages: [...] } state.
__aborted__ — terminal marker emitted when the run was stopped via the abort endpoint.
__suspended__ — terminal marker emitted when a server restart suspended the run before it finished; resend the same request to resume it.
__usage__ — always the last frame on the stream, whether the run completed, was aborted, or errored (all counts are 0 and models is empty if the request was rejected before any LLM call). Carries type: "usage" and { models, llmCalls, inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, totalTokens } under usage. There is no cost field.

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

Suspensions: when the server serving a run shuts down (a deployment, a scale-down), the run is stopped at the next step boundary with its progress saved, and the stream emits { "id": "__suspended__", "type": "suspend", "code": "chat_suspended", "retryable": true, "messageId": "<id>", "error": "<message>" } before it closes. The content received so far is partial. Resend the same request — the same chatId, input and messageId — and the run continues from where it stopped (if the original request had no chatId, add the one returned as state.chatId on its __cutoff__ frame); the response replays the thread and then streams the rest of the turn. input may be omitted: chatId plus the suspended messageId resumes it too. A read of the thread (no input, no messageId) reports a pending suspension as state.suspended.messageId on __cutoff__. A request for a different message ends the suspended turn. A suspended turn stays resumable for 24 hours; after that, resending the request returns the thread as it stands, with the partial turn, without rerunning it.

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. If that message was suspended by a server restart, the request resumes it.

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>",
  "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>"
    ]
  }
}
'

import requests

url = "https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state"

payload = {
    "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>"]
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>']
    }
  })
};

fetch('https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state"

	payload := strings.NewReader("{\n  \"activeBranchName\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"images\": [\n    {\n      \"data\": \"<string>\",\n      \"mimeType\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"input\": \"<string>\",\n  \"isDefaultBranch\": true,\n  \"messageId\": \"<string>\",\n  \"sessionSettings\": {\n    \"email\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"groups\": [\n      \"<string>\"\n    ],\n    \"internalId\": \"<string>\",\n    \"publicDashboardId\": \"<string>\",\n    \"roles\": [\n      \"<string>\"\n    ],\n    \"securityContext\": {},\n    \"userAttributes\": [\n      \"<unknown>\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"activeBranchName\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"images\": [\n    {\n      \"data\": \"<string>\",\n      \"mimeType\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"input\": \"<string>\",\n  \"isDefaultBranch\": true,\n  \"messageId\": \"<string>\",\n  \"sessionSettings\": {\n    \"email\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"groups\": [\n      \"<string>\"\n    ],\n    \"internalId\": \"<string>\",\n    \"publicDashboardId\": \"<string>\",\n    \"roles\": [\n      \"<string>\"\n    ],\n    \"securityContext\": {},\n    \"userAttributes\": [\n      \"<unknown>\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"activeBranchName\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"images\": [\n    {\n      \"data\": \"<string>\",\n      \"mimeType\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"input\": \"<string>\",\n  \"isDefaultBranch\": true,\n  \"messageId\": \"<string>\",\n  \"sessionSettings\": {\n    \"email\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"groups\": [\n      \"<string>\"\n    ],\n    \"internalId\": \"<string>\",\n    \"publicDashboardId\": \"<string>\",\n    \"roles\": [\n      \"<string>\"\n    ],\n    \"securityContext\": {},\n    \"userAttributes\": [\n      \"<unknown>\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

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

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

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

code

enum<string>

Machine-readable reason the run ended early. Present only on the __aborted__ and __suspended__ frames.

Available options:

chat_aborted,

chat_suspended

content

string

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

error

string

Present on error lines ({ "error": "<message>" }), which carry no message fields, and on the __aborted__ and __suspended__ frames.

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), __state__ (thread state snapshot), __aborted__ (run stopped via the abort endpoint), __suspended__ (run suspended by a server restart; resend to resume), and __usage__ (always the last frame, carries model/token counts under usage). 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.

messageId

string

Present only on the __suspended__ frame: the messageId of the suspended turn, to resend.

retryable

boolean

Present only on the __suspended__ frame, always true: resending the same request resumes the run.

role

enum<string>

Absent on error lines and on the __usage__ frame.

Available options:

user,

assistant

sort

number

Message ordering sequence. Absent on the __usage__ frame.

state

object

Streaming state. Carries { isStreaming, chatId } (plus suspended.messageId when a suspended turn is pending) 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

type

enum<string>

Present only on a terminal sentinel: abort on __aborted__, suspend on __suspended__, usage on __usage__. Absent on every other message.

Available options:

abort,

suspend,

usage

usage

object

Model and token counts for the run. Present only on the __usage__ frame.

Show child attributes

Getting Started

Core Data Endpoints

AI Endpoints

Platform Endpoints

Stream chat state

Authorizations

Body

Response