--- title: Chat API description: The Chat API enables real-time conversations with AI agents for analytics and data exploration. --- The Chat API is available on [Premium and Enterprise plans](https://cube.dev/pricing). ## Endpoint The endpoint can be addressed either by agent or by deployment. Addressed by agent, it talks to that specific agent: ```text https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state ``` Copy the exact URL from your agent settings (**Chat API URL** field) in **Admin → Agents**. Addressed by deployment, it talks to the deployment's Auto agent, or to its [default agent](/admin/ai/multi-agent#default-agent-and-auto) when an admin has turned Auto off: ```text https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId}/chat/stream-chat-state ``` Copy the exact URL from the deployment's **Settings → API credentials → Chat API** tab, also reachable from the **Chat** entry on the deployment's **Status** page. The two forms differ in which authentication they accept: | URL form | [API key](#api-key-authentication) | [Cube token](#cube-token-authentication) | |---|:---:|:---:| | `/agents/{agentId}/…` | ✓ | ✓ | | `/deployments/{deploymentId}/…` | — | ✓ | The deployment form is served **only** through the Cube token exchange, which is what resolves the deployment's agent — an API key carries no agent, so a request without `{agentId}` in the path is rejected with `403 agentId is required for Api-Key authentication`. Because [Cube token authentication](#cube-token-authentication) is disabled by default, the deployment form works only once it is enabled in **Settings** → **Configuration** → **Use Cube authentication for Chat and embedding APIs**. Request body and streaming response are identical for both. ## Overview The Chat API enables real-time streaming conversations with Cube's AI agents. This endpoint allows applications to integrate AI-powered analytics conversations directly into their user interfaces. ## Authentication Accounts are limited to 10,000 non-ephemeral external users. To increase this limit, please contact support. All users created using this API are ephemeral by default and will be removed after `sessionSettings.ephemeralTtlSeconds` (1 week by default). If users need to be persisted, pass `isEphemeral: false` in `sessionSettings`. Ephemeral users are guaranteed to not live longer than `sessionSettings.ephemeralTtlSeconds`. The Chat API supports two authentication methods: - [API key authentication](#api-key-authentication) — pass a Cube [API key][ref-api-keys] in the `Authorization` header. - [Cube token authentication](#cube-token-authentication) — pass your deployment's own [Cube token][ref-jwt-auth] (JWT) in the `X-Cube-Auth-Token` header. ### API key authentication Pass your [API key][ref-api-keys] directly to the Chat API endpoint. The session will be created automatically based on the `externalId` provided: ```javascript // Copy the Chat API URL from your agent settings (Admin → Agents → Chat API URL field) const CHAT_API_URL = 'YOUR_CHAT_API_URL'; const response = await fetch( CHAT_API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Api-Key ${API_KEY}', }, body: JSON.stringify({ input: 'What were the total sales last month?', sessionSettings: { externalId: 'user@example.com', email: 'user@example.com', // optional userAttributes: [ // optional { name: 'city', value: 'San Francisco' } ] } }), } ); // Handle streaming response const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; console.log(decoder.decode(value)); } ``` ### Cube token authentication Cube token authentication for the Chat API is disabled by default. You can enable it in your deployment settings: **Settings** → **Configuration** → **Use Cube authentication for Chat and embedding APIs**. Instead of an API key, the Chat API can authenticate requests with your deployment's own [Cube authentication][ref-jwt-auth] — the same JSON Web Tokens (JWTs) your application already uses with the Core Data APIs. Cube validates the token using the deployment's existing authentication configuration: the API secret, JWKS, or a custom [`check_auth`][ref-config-check-auth] implementation. This is useful for [headless embedding][ref-headless-embedding]: your application issues a single kind of token, and the same token works for both data queries and AI-powered conversations. Pass the token in the `X-Cube-Auth-Token` header instead of the `Authorization` header: ```javascript // Copy the Chat API URL from your agent settings (Admin → Agents → Chat API URL field) const CHAT_API_URL = 'YOUR_CHAT_API_URL'; const response = await fetch( CHAT_API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Cube-Auth-Token': CUBE_TOKEN, }, body: JSON.stringify({ input: 'What were the total sales last month?' }), } ); ``` If the request also carries an `Authorization` header, it takes precedence and the `X-Cube-Auth-Token` header is ignored. Send exactly one of the two. To be accepted by the Chat API, the token must be valid for the deployment and include the following claims in its payload: - `externalId` (required) — unique identifier for the external user. Normalized to lowercase, so ids that differ only in casing map to the same user. When `externalId` is not present, the standard JWT `sub` claim is used instead. - `scope` (required) — an array of scopes that must include `chat`. - `email` (optional) — email address to store on the provisioned external user. ```javascript const jwt = require("jsonwebtoken") const cubeToken = jwt.sign( { externalId: "user@example.com", scope: ["chat"], // Security context claims, e.g.: tenant_id: "acme" }, process.env.CUBEJS_API_SECRET, { expiresIn: "1h" } ) ``` The `chat` scope is asserted on the token's *resolved security context*. With the default JWT authentication the security context is simply the token payload, so including `scope: ["chat"]` in the token is enough. If your deployment uses a custom [`check_auth`][ref-config-check-auth] implementation that rewrites the security context, make sure the resolved security context carries `scope: ["chat"]` for tokens that should be allowed to use the Chat API. When Cube token authentication is used: - The external user is identified by the `externalId` (or `sub`) claim, and their security context is resolved from the token claims — so you don't need to pass identity fields in `sessionSettings`; users are provisioned automatically from the token. - The agent queries the deployment with the same token you sent, so row-level security and any other security-context-based access controls apply to the conversation exactly as they apply to your direct API queries. The exception is a [security context in the request body](#security-context-in-the-request-body). - Tokens that are invalid for the deployment, miss the `externalId` (or `sub`) claim, or don't carry the `chat` scope are rejected. #### Security context in the request body Passing a security context in the request body with Cube token authentication is not enabled by default. To use it, contact the Cube team. Until it is enabled, a `sessionSettings.securityContext` sent with a Cube token is ignored. With Cube token authentication, the security context comes from the token claims, and that covers almost every use case. Rarely, the security context is too large to fit in a token. The token travels in the `X-Cube-Auth-Token` header, and servers, proxies and load balancers limit the size of request headers, commonly to 8–16 KB. A security context that lists thousands of account IDs, for example, can exceed that limit. For these cases, the Chat API accepts the security context in the request body as `sessionSettings.securityContext`, up to 64 KB (65,536 bytes of JSON): ```javascript const cubeToken = jwt.sign( { externalId: "user@example.com", scope: ["chat", "chat-security-context"] }, process.env.CUBEJS_API_SECRET, { expiresIn: "1h" } ) const response = await fetch(CHAT_API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Cube-Auth-Token': cubeToken, }, body: JSON.stringify({ input: 'What were the total sales last month?', sessionSettings: { securityContext: { tenant_id: "acme", account_ids: ["acc_00000001", "acc_00000002" /* , … */] } } }), }); ``` This is how it works: - The token must include `chat-security-context` in its `scope`, in addition to `chat`. Like `chat`, the scope is checked on the token's resolved security context. A token without it that sends a security context in the body is rejected. - Cube stores the security context on the external user identified by the token's `externalId` (or `sub`) claim, and the agent's queries for that user run with it. It **replaces** the token claims as the security context of these queries, so include every claim your data model, access policies and `query_rewrite` read. - Later requests that omit `securityContext`, or send `null`, reuse the stored security context, so you don't need to send it with every message. - Sending a new object replaces the stored security context. Sending `{}` clears it, and the agent goes back to querying with the token you send. - The stored security context outlives the token: a new token doesn't refresh it. When a user's access changes, send the new security context, or `{}`, before their next message. Sending it on the first request of each session keeps it current. - The stored security context is used only while the token carries the `chat-security-context` scope. A token without the scope that omits the security context is accepted, and the agent queries with that token. - The token still authenticates every request and is validated with the deployment's authentication configuration, including a custom [`check_auth`][ref-config-check-auth]. - Claims Cube reserves are dropped from the stored security context: `scope`, `cubeCloudScope`, `cubeCloud`, `requestSource`, `override`, `iat`, `exp`, `aud`, `iss` and `sub`. - After the security context changes, the agent's queries can keep using the previous one for up to 15 seconds. - The stored security context applies to the agent's queries only. A query your application runs itself with the token, for example when [loading all results](#loading-all-results), uses the token claims. A request that can't store the security context fails before the turn starts, with an error in the stream, e.g.: ```json {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Cube auth failed: sessionSettings.securityContext must not exceed 65536 bytes"}} ``` **Request Body Fields:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `input` | string | No | The user's message or question. If omitted returns current state of thread with provided chatId. | | `chatId` | string | No | Chat thread ID. If omitted, a new thread is created automatically. If provided, it should match the previously returned `chatId` from a message with id `__cutoff__` sent as the `state.chatId` field. | | `messageId` | string | No | Client-provided identifier for the user message. Must match the format `-message` (a 13+ digit Unix timestamp in milliseconds followed by `-message`), e.g. `1717500000000-message`. Used to make requests idempotent — see [Idempotency](#idempotency). | | `sessionSettings.externalId` | string | No | Unique identifier for the external user, lowercase and without spaces. Either `externalId` or `internalId` should be provided. | | `sessionSettings.internalId` | string | No | Email address of an internal Cube Cloud user. Either `externalId` or `internalId` should be provided. | | `sessionSettings.email` | string | No | User's email address | | `sessionSettings.userAttributes` | array | No | Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`. | | `sessionSettings.groups` | string[] | No | Array of group names the user belongs to. Not allowed with `internalId`. | | `sessionSettings.securityContext` | object | No | Custom security context object passed to Cube queries. Not allowed with `internalId`. With Cube token authentication, see [Security context in the request body](#security-context-in-the-request-body). | | `sessionSettings.allowChatWorkspaceAuthoring` | boolean | No | Restricts this session from creating or modifying persistent workspace content when set to `false`. Ad-hoc analysis and inline tables/charts remain available, but the agent cannot save or update standalone explorations/reports, create or modify workbooks, or create or publish dashboards. Omitted or `true` never grants more than the user's role allows. An `externalId` session is never in [Creator Mode](/embedding/iframe/creator-mode) (`creatorMode`), so its agent does not author workspace content either way; an `internalId` session keeps the user's role-derived authoring. | | `sessionSettings.timezone` | string | No | IANA time zone of this session's user, e.g. `America/New_York`. Queries the agent runs are executed in it. Must be set explicitly — never inferred from `securityContext` or `userAttributes`. Omitted or unusable falls back to the deployment's default time zone rather than failing the session. | | `activeBranchName` | string | No | Name of a development branch to use for the chat session. When provided, queries run against the specified branch instead of the main branch. | | `isDefaultBranch` | boolean | No | Whether the specified `activeBranchName` is the default branch. Defaults to `true` when `activeBranchName` is not set, and `false` when it is. Set to `true` if passing the main/production branch name. | | `streamRunStatus` | boolean | No | When `true`, the stream reports the setup phase of the turn as `__status__` frames — see [Run Status](#run-status). Defaults to `false`. | When using `internalId`, the user must already exist in Cube Cloud. You cannot specify `roles`, `groups`, `userAttributes`, or `securityContext` with `internalId` — the internal user's existing permissions are used instead. ### User Attributes User attributes allow you to pass contextual information about the user to the AI agent. This enables personalized responses and automatic data filtering based on user permissions through row-level security policies. User attributes must first be configured in your Cube admin panel before they can be used. See the [User Attributes documentation](/admin/users-and-permissions/user-attributes) for setup instructions. **Supported Fields:** - `externalId` (optional): Unique identifier for the external user. Either `externalId` or `internalId` should be provided. - `internalId` (optional): Email address of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided. - `email` (optional): User's email address - `userAttributes` (optional): Array of key-value pairs containing user metadata. Only available with `externalId`. **User Attribute Structure:** ```javascript { name: 'string', // Must match an attribute name configured in admin panel value: 'string' // Attribute value (e.g., 'San Francisco', 'Engineering') } ``` **How User Attributes Work:** 1. **Row-Level Security**: Automatically filter data based on user attributes through access policies 2. **Personalized Responses**: AI agent can tailor responses based on user context 3. **Access Control**: Restrict data access to only what the user should see **Example Use Cases:** - Filter sales data by user's assigned territory - Show only customers from user's city - Limit financial data based on user's department - Personalize dashboards by user role The attributes passed during session generation become available as `userAttributes.{attributeName}` for use in access policies. ## Endpoint Reference **POST** ```text https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId}/chat/stream-chat-state ``` Copy the complete Chat API URL from your agent settings (**Chat API URL** field) in **Admin → Agents**, or — for the deployment form — from **Settings → API credentials → Chat API**. ### Path Parameters - **`cloudRegion`** (string): The cloud region identifier (e.g., "gcp-us-central1") - **`accountName`** (string, required): The account identifier (e.g., "acme"). It is in your account URL, e.g. https://acme.cubecloud.dev - **`agentId`** (string, required for the agent form): The AI agent identifier (e.g., "1"). You can find it in **Admin → Agents → Click on Agent row in the table**. - **`deploymentId`** (string, required for the deployment form): The deployment identifier (e.g., "9"). It is in the deployment URL, e.g. https://acme.cubecloud.dev/d/9. Resolves to the deployment's Auto agent, or to its [default agent](/admin/ai/multi-agent#default-agent-and-auto) when Auto is turned off. ### Request Body - **`input`** (string): User message or query to send to the AI agent, e.g. "What is our revenue last month?". If omitted, returns current state of thread with provided `chatId`. - **`chatId`** (string): Chat thread ID. If omitted, a new thread is created automatically. If provided, it should match the previously returned `chatId` from a message with id `__cutoff__`. - **`messageId`** (string): Client-provided identifier for the user message. Must match the format `-message` (a 13+ digit Unix timestamp in milliseconds followed by `-message`), e.g. `1717500000000-message`. Used to make requests idempotent — see [Idempotency](#idempotency). - **`sessionSettings`** (object, required for API key authentication; ignored with Cube token authentication, where identity comes from the token claims, except for `securityContext` — see [Security context in the request body](#security-context-in-the-request-body)): Session configuration for the user - **`externalId`** (string): Unique identifier for the external user. Either `externalId` or `internalId` should be provided. - **`internalId`** (string): Email address of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided. - **`email`** (string): User's email address - **`userAttributes`** (array): Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`. - **`groups`** (string[]): Array of group names for user. Not allowed with `internalId`. - **`securityContext`** (object): Custom security context object passed to Cube queries. Not allowed with `internalId`. With Cube token authentication, see [Security context in the request body](#security-context-in-the-request-body). - **`activeBranchName`** (string): Name of a development branch to use for the chat session. When provided, queries run against the specified branch instead of the main branch. - **`isDefaultBranch`** (boolean): Whether the specified `activeBranchName` is the default branch. Defaults to `true` when `activeBranchName` is not set, and `false` when it is. Set to `true` if passing the main/production branch name. - **`streamRunStatus`** (boolean): When `true`, the stream reports the setup phase of the turn as `__status__` frames — see [Run Status](#run-status). Defaults to `false`. ## Idempotency You can pass a client-provided `messageId` in the request body to make Chat API requests idempotent. The value must match the format `-message`, where `` is a Unix timestamp in milliseconds with 13 or more digits, e.g. `1717500000000-message`. 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. This is useful for retrying after a dropped connection: the client can replay the same request and resume receiving the stream from the current point without producing duplicate assistant messages. If the message was [suspended](#suspended-runs) by a server restart, the same request resumes it. Without a matching `messageId`, sending a new message to a thread that is already streaming returns a `Streaming for thread is in progress` error. ## Response Format The API returns streaming JSON responses. Each line contains a separate JSON object representing a chat message, a state update, or a usage frame. ### Response Fields - **`id`** (string): Unique message identifier. Sentinel values: `__cutoff__`, `__state__`, `__status__`, `__aborted__`, `__suspended__`, and `__usage__` - **`role`** (string): Message sender: `"user"` or `"assistant"`. Absent on error lines and on the `__status__` and `__usage__` frames - **`error`** (string): Present on the `__aborted__` and `__suspended__` frames, and on error lines — mid-stream failures arrive as a standalone `{ "error": "" }` line rather than a non-200 status, and such a line carries no message fields - **`content`** (string): Message content (streamed incrementally for assistant messages) - **`thinking`** (string): Agent's internal reasoning process (visible in development mode) - **`toolCall`** (object): Information about tool calls made by the agent during processing - **`name`** (string): Name of the tool being called - **`input`** (string): JSON string containing the input parameters for the tool - **`result`** (string): JSON string containing the tool's response (only present when tool call is complete) - **`graphPath`** (string[]): Identifies which node of the agent graph produced this message. For example, `["cube_data_analyst_agent"]` for the main agent node or `["cube_data_analyst_agent", "tools"]` for tool calls. Messages with `graphPath[0] === "final"` represent the final consolidated answer. - **`isDelta`** (boolean): Whether this is an incremental content update - **`isInProcess`** (boolean): Whether the message is still being generated - **`sort`** (number): Message ordering sequence number. Absent on the `__status__` and `__usage__` frames - **`state`** (object): Current streaming state information - **`type`** (string): Present only on the `__status__` (`"status"`), `__aborted__` (`"abort"`), `__suspended__` (`"suspend"`) and `__usage__` (`"usage"`) frames - **`status`** (string): Present only on the `__status__` frame — the setup phase of the turn: `"waiting_for_deployment"`, `"initializing"`, or `"running"` - **`code`** (string): Present only on the `__aborted__` (`"chat_aborted"`) and `__suspended__` (`"chat_suspended"`) frames - **`retryable`** (boolean): Present only on the `__suspended__` frame, always `true` - **`messageId`** (string): Present only on the `__suspended__` frame — the `messageId` of the suspended turn, to resend - **`usage`** (object): Present only on the `__usage__` frame — `models` (string[]), `llmCalls`, `inputTokens`, `outputTokens`, `cacheWriteTokens`, `cacheReadTokens`, `totalTokens` (numbers) The stream always ends with one additional frame, `id: "__usage__"` (see the Usage Message example below). Treat it like the `__cutoff__`, `__state__`, `__status__`, `__aborted__` and `__suspended__` frames: filter it out of anything rendered as a chat message. ### Response Examples The API returns a series of JSON objects, each on a separate line. Here's what a typical conversation looks like: **Initial State Message:** ```json { "id": "__cutoff__", "role": "assistant", "state": { "isStreaming": false }, "sort": 0 } ``` **User Message Echo:** ```json { "id": "1732512345678-message", "role": "user", "content": "Show me revenue trends for the last 6 months", "isDelta": false, "sort": 1 } ``` **Assistant Response Start:** ```json { "id": "cdfe1a84-08d7-40b9-8b1c-e7e3a698647e", "role": "assistant", "content": "", "thinking": "", "graphPath": ["cube_data_analyst_agent"], "isStructuredResponse": false, "isInProcess": true, "isDelta": true, "sort": 2 } ``` **Thinking Process:** ```json { "id": "cdfe1a84-08d7-40b9-8b1c-e7e3a698647e", "role": "assistant", "content": "", "thinking": "The user wants to see revenue trends for the last 6 months. I need to query the revenue data and create a visualization.", "graphPath": ["cube_data_analyst_agent"], "isStructuredResponse": false, "isInProcess": true, "isDelta": true, "sort": 3 } ``` **Content Streaming:** ```json { "id": "cdfe1a84-08d7-40b9-8b1c-e7e3a698647e", "role": "assistant", "content": "I'll help you analyze revenue trends for the last 6 months. Let me query the data and create a visualization.", "thinking": "", "graphPath": ["cube_data_analyst_agent"], "isStructuredResponse": false, "isInProcess": true, "isDelta": true, "sort": 4 } ``` **Tool Call Initiated:** ```json { "id": "4849adb2-b55d-4afe-946b-fc117bcadaf5", "role": "assistant", "toolCall": { "name": "cubeMeta", "input": "{\"searchQuery\":\"revenue trends\"}" }, "isInProcess": true, "graphPath": ["cube_data_analyst_agent", "tools"], "isStructuredResponse": false, "isDelta": false, "sort": 5 } ``` **Tool Call Result:** ```json { "id": "4849adb2-b55d-4afe-946b-fc117bcadaf5", "role": "assistant", "toolCall": { "name": "cubeMeta", "input": "{\"searchQuery\":\"revenue trends\"}", "result": "{\"cubes\":[{\"name\":\"Revenue\",\"measures\":[\"Revenue.totalRevenue\",\"Revenue.monthlyGrowth\"]}]}" }, "isInProcess": false, "graphPath": ["cube_data_analyst_agent", "tools"], "isStructuredResponse": false, "isDelta": false, "sort": 6 } ``` **SQL Query Tool Call:** ```json { "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890", "role": "assistant", "toolCall": { "name": "cubeSqlApi", "input": "{\"query\":\"SELECT Revenue.totalRevenue, Revenue.month FROM Revenue WHERE Revenue.dateRange BETWEEN '2024-01-01' AND '2024-06-30' ORDER BY Revenue.month\"}" }, "isInProcess": true, "graphPath": ["cube_data_analyst_agent", "tools"], "isStructuredResponse": false, "isDelta": false, "sort": 7 } ``` **SQL Query Result:** ```json { "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890", "role": "assistant", "toolCall": { "name": "cubeSqlApi", "input": "{\"query\":\"SELECT Revenue.totalRevenue, Revenue.month FROM Revenue WHERE Revenue.dateRange BETWEEN '2024-01-01' AND '2024-06-30' ORDER BY Revenue.month\"}", "result": "{\"data\":[{\"Revenue.totalRevenue\":1800000,\"Revenue.month\":\"2024-01\"},{\"Revenue.totalRevenue\":1950000,\"Revenue.month\":\"2024-02\"},{\"Revenue.totalRevenue\":2300000,\"Revenue.month\":\"2024-03\"},{\"Revenue.totalRevenue\":2100000,\"Revenue.month\":\"2024-04\"},{\"Revenue.totalRevenue\":2250000,\"Revenue.month\":\"2024-05\"},{\"Revenue.totalRevenue\":2400000,\"Revenue.month\":\"2024-06\"}],\"annotation\":{\"measures\":{\"Revenue.totalRevenue\":{\"title\":\"Total Revenue\",\"type\":\"number\"}},\"dimensions\":{\"Revenue.month\":{\"title\":\"Month\",\"type\":\"time\"}}}}" }, "isInProcess": false, "graphPath": ["cube_data_analyst_agent", "tools"], "isStructuredResponse": false, "isDelta": false, "sort": 8 } ``` **Final Complete Message:** ```json { "id": "cdfe1a84-08d7-40b9-8b1c-e7e3a698647e", "role": "assistant", "content": "I'll help you analyze revenue trends for the last 6 months. Let me query the data and create a visualization.\n\nBased on your revenue data, here are the key trends:\n\n📈 **Overall Growth**: 15% increase over the 6-month period\n💰 **Peak Month**: March 2024 with $2.3M revenue\n📊 **Steady Growth**: Consistent month-over-month growth of 2-3%\n\nWould you like me to break this down by product category or region?", "thinking": "", "graphPath": ["cube_data_analyst_agent"], "isStructuredResponse": false, "isInProcess": false, "isDelta": false, "sort": 9 } ``` **Thread State Snapshot:** ```json { "id": "__state__", "role": "assistant", "state": { "messages": [{ "lc": 1, "type": "constructor", "id": ["langchain_core", "messages", "HumanMessage"], "kwargs": { "content": "Show me revenue trends for the last 6 months" } }] }, "isDelta": false, "sort": 10 } ``` **Usage Message:** ```json { "id": "__usage__", "type": "usage", "usage": { "models": ["claude-sonnet-5"], "llmCalls": 7, "inputTokens": 18412, "outputTokens": 2280, "cacheWriteTokens": 31006, "cacheReadTokens": 264118, "totalTokens": 315816 } } ``` This is always the last frame on the stream, sent whether the run completed, was aborted, or errored — when the request is rejected before any LLM call, the counts are all `0` and `models` is empty. `usage.models` lists the distinct models used, and for a [BYOM](/admin/ai/bring-your-own-model) model is normalized to strip infrastructure detail (e.g. a Bedrock inference-profile ARN is reduced to its model name) rather than the raw configured identifier. The frame reports tokens only — there is no cost field. ### Run Status When the request sets `streamRunStatus: true`, the stream reports the setup phase of the turn as `__status__` frames: ```json { "id": "__status__", "type": "status", "status": "waiting_for_deployment" } ``` The stream sends one frame for each setup phase of the turn, in this order: - `waiting_for_deployment` — sent when the request starts, until the Cube deployment answers. - `initializing` — the agent sets up (rules, skills, certified queries, docs) before its first model call. - `running` — the agent has started; the setup ends. Use these frames to show progress before the first assistant message arrives, and filter them out of anything rendered as a chat message. They are live-only: a later read of the thread does not include them. ### Suspended Runs When the server running a chat shuts down (for example, during a deployment or a scale-down), the run is stopped at the next step boundary with its progress saved, and the stream emits a `__suspended__` frame before it closes: ```json { "id": "__suspended__", "type": "suspend", "code": "chat_suspended", "retryable": true, "messageId": "1732512345678-message", "error": "The server restarted before the agent finished responding; retry the same request to resume" } ``` The HTTP status is still `200`, and the content received so far is partial. Scan the stream for this frame rather than checking only the last line — the `__usage__` frame still follows it. To continue the turn, resend the **same** request — the same `chatId`, `input` and `messageId`. If the original request had no `chatId`, add the one returned as `state.chatId` on its `__cutoff__` frame. The run picks up where it stopped instead of starting over: the response replays the thread and then streams the rest of the turn. `input` may be omitted — `chatId` plus the suspended `messageId` is enough. Sending a different message instead ends the suspended turn, and the new run builds on what that turn already did. A suspended turn stays resumable for 24 hours. After that, resending the request neither reruns the turn nor fails: it returns the thread as it stands, with the partial turn, and a new message continues from there. A read of the thread (a request with `chatId` but no `input` and no `messageId`) reports a pending suspension as `state.suspended.messageId` on the `__cutoff__` frame, so a client that lost the stream can still find the turn to resume. Always send a `messageId` (see [Idempotency](#idempotency)) so a suspended turn can be resumed with the exact same request. ```javascript async function streamChat(body) { const response = await fetch(CHAT_API_URL, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Api-Key ${API_KEY}` }, body: JSON.stringify(body), }); let suspended = null; for await (const line of readLines(response.body)) { if (!line) continue; const msg = JSON.parse(line); // A new thread's id arrives on __cutoff__; keep it so a resend resumes that thread if (msg.id === "__cutoff__" && msg.state?.chatId) body.chatId = msg.state.chatId; if (msg.id === "__suspended__") suspended = msg; // ...handle other messages. A resumed response replays the thread first, // so upsert by `id` (don't append) before rendering } return suspended; } const body = { input: "What is our revenue last month?", messageId: `${Date.now()}-message`, sessionSettings }; // Resend the same body until the turn completes (a few attempts at most) let attempts = 0; while ((await streamChat(body)) && ++attempts < 3) {} ``` ### Getting the Final Assistant Message When consuming the streamed NDJSON response, you may want to extract only the final answer that the agent produced — for example, to display it in a chat UI or to store it for later reference. The agent graph emits many intermediate messages (thinking steps, tool calls, incremental deltas, state updates, etc.). To isolate the **final answer**, filter the streamed messages using these two conditions: 1. `role === "assistant"` — only assistant messages. 2. `graphPath[0] === "final"` **and** `graphPath.length <= 2` — messages produced by the "final" node of the agent graph. The **last** message that satisfies both conditions is the final answer. ```javascript // Collect all streamed messages first const messages = []; for await (const line of readLines(response.body)) { if (line) { messages.push(JSON.parse(line)); } } // Filter for final-answer messages const finalMessages = messages.filter( (msg) => msg.role === "assistant" && Array.isArray(msg.graphPath) && msg.graphPath[0] === "final" && msg.graphPath.length <= 2 ); // The last one is the definitive final answer const finalAnswer = finalMessages[finalMessages.length - 1]; console.log("Final answer:", finalAnswer?.content); ``` The `graphPath` property is an array of strings that traces the path through the agent's internal execution graph. Intermediate nodes (e.g., `["cube_data_analyst_agent"]` or `["cube_data_analyst_agent", "tools"]`) produce working messages, while the `"final"` node emits the consolidated response that should be presented to the user. ### Tool Calls When the AI agent performs actions like querying data or searching metadata, tool calls are included in the response stream. These provide transparency into the agent's reasoning and data retrieval process. All tool results are returned as **JSON strings** within the `toolCall.result` field, not as parsed JSON objects. You must parse these strings to access the structured data. **Key Points:** - `toolCall.input` - JSON string containing tool parameters - `toolCall.result` - JSON string containing tool response (only present when `isInProcess: false`) - Both input and result contain escaped JSON that requires parsing - Results may contain nested JSON structures, especially for complex data queries - Error responses are also JSON strings with consistent error formatting **Parsing Example:** ```javascript // Parse the tool result JSON string const toolResult = JSON.parse(message.toolCall.result); if (toolResult.error) { console.error('Tool error:', toolResult.error); } else { // Handle successful result based on tool type if (message.toolCall.name === 'cubeSqlApi') { const data = toolResult.data; const annotation = toolResult.annotation; const isAnswer = toolResult.purpose === 'answer'; // see "Picking the answer" } } ``` #### cubeMeta Searches cube metadata and schema information The `cubeMeta` tool returns cube schema information as a JSON string. When successful, the result contains: ```json { "toolCall": { "name": "cubeMeta", "input": "...", "result": "..." } } ``` **Input Structure:** ```json { "searchQuery": "sales pipeline revenue" } ``` **Input Fields:** - `searchQuery` (string): Search query for data model **Result Structure:** ```json { "cubes": [ { "name": "sales_pipeline_view", "type": "view", "title": "Sales Pipeline View", "members": [ { "name": "sales_pipeline_view.company_name", "title": "Company Name", "description": "Name of the company/prospect", "type": "string" }, { "name": "sales_pipeline_view.deal_amount", "title": "Deal Amount", "description": "Total deal value", "type": "number" }, { "name": "sales_pipeline_view.stage", "title": "Sales Stage", "description": "Current stage of the deal (Lead, Demo, Negotiation, Won, Lost, etc.)", "type": "string" }, { "name": "sales_pipeline_view.count", "title": "Deal Count", "description": "Total number of deals", "type": "number", "aggType": "count" } ] }, { "name": "revenue_view", "type": "view", "title": "Revenue View", "members": [ { "name": "revenue_view.total_amount", "title": "Total Revenue", "description": "Sum of all revenue", "type": "number", "aggType": "sum" }, { "name": "revenue_view.month", "title": "Revenue Month", "description": "Month of revenue recognition", "type": "time" }, { "name": "revenue_view.is_recurring", "title": "Is Recurring Revenue", "description": "Whether this is recurring or one-time revenue", "type": "boolean" } ] } ], "searchQuery": "sales pipeline revenue" } ``` **Result Fields:** - `cubes` (array): Available cube/view definitions with members - `searchQuery` (string): The original search query used #### cubeSqlApi Executes SQL queries against cube data The `cubeSqlApi` tool executes SQL queries and returns data with metadata. The input typically includes additional context fields: ```json { "toolCall": { "name": "cubeSqlApi", "input": "...", "result": "..." } } ``` **Input Structure:** ```json { "sqlQuery": "SELECT deals_view.company_name, deals_view.deal_name FROM deals_view WHERE deals_view.stage = 'Negotiation' LIMIT 10", "queryTitle": "Sales Pipeline Overview", "description": "Retrieving deal information from the deals view for current negotiations", "userRequest": "show me current deals in negotiation", "purpose": "answer", "memoryId": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6", "vegaSpec": "vega lite v5 visualization spec as JSON string" } ``` **Input Fields:** - `sqlQuery` (string): The SQL query to execute - `queryTitle` (string): Human-readable title for the query - `description` (string): Detailed description of what the query does - `userRequest` (string): Original user request that triggered this query - `purpose` (string): Why the agent runs this query — see [Picking the answer](#picking-the-answer): - `answer`: the agent presents this query's rows to the user - `lookup`: the query only finds something a later query needs, such as an ID, a name or which values exist - `memoryId` (string): Reference to previous analysis or context - `vegaSpec` (string): Vega-Lite v5 visualization specification as JSON string (when visualization is generated) - `periodComparisons` (array): Period comparisons the agent asked for, e.g., month over month, with `measure`, `timeDimension`, `offset` and `outputs`. Present when the user asks to compare periods — see [Period comparisons][ref-mcp-period-comparisons] **Result Structure:** ```json { "sqlQuery": "SELECT deals_view.company_name, deals_view.name AS deal_name...", "queryTitle": "Current Deals Overview", "description": "Retrieving deals showing company names, deal names, stages...", "userRequest": "show me deals", "purpose": "answer", "schema": [ { "name": "company_name", "column_type": "String" }, { "name": "deal_name", "column_type": "String" }, { "name": "stage", "column_type": "String" }, { "name": "tenant_name", "column_type": "String" }, { "name": "activity_score", "column_type": "Double" }, { "name": "deal_count", "column_type": "Int64" } ], "data": [ ["Acme Corp", "Enterprise Solution", "Negotiation", "acme-workspace", "245", "1"], ["Beta Industries", "Analytics Platform", "Testing", "beta-analytics", "189", "1"], ["Gamma LLC", "Data Pipeline", "Demo", "gamma-data", "156", "1"] ], "totalRows": 25, "uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6", "vegaSpec": "vega lite v5 visualization spec as JSON string" } ``` **Result Fields:** - `sqlQuery` (string): The executed SQL query - `queryTitle` (string): Human-readable title for the query - `description` (string): Detailed description of what the query does - `userRequest` (string): Original user request that triggered this query - `purpose` (string): `answer` or `lookup`, as set in the input - `schema` (array): Column definitions with `name` and `column_type` for each field - `data` (array): Query result rows as arrays of values - `totalRows` (number): Total number of rows returned - `truncated` (boolean): `true` when `data` holds fewer rows than `totalRows` — see [Loading all results](#loading-all-results) - `periodComparisonColumns` (array): Period comparison columns added to `schema` and `data`, each with its `name`, `title`, `measure`, `timeDimension`, `offset` and `output`. Present when the query has period comparisons - `periodComparisonErrors` (array of strings): Why a period comparison couldn't be computed. Its columns are left out; the rest of the result is unaffected - `uuid` (string): Unique identifier for this query result - `vegaSpec` (string): Vega-Lite v5 visualization specification as JSON string (when visualization is generated) #### Picking the answer One chat turn can run several `cubeSqlApi` queries: lookups that find an ID or a name, and the queries whose rows answer the question. Use the results with `purpose: "answer"`. There can be more than one, e.g., when the answer is two tables. Do not take the last result: it can be a lookup. Results in older chats can have no `purpose`. For those, fall back to the last result. Look only at the current turn. A resumed response and a read of the thread replay the earlier turns too, and a message can arrive in several frames. Keep the last frame for each `id`, then take the messages after the last user message. ```javascript // `messages`: every parsed line of the response stream const latest = new Map(); for (const m of messages) latest.set(m.id, m); const thread = [...latest.values()]; const turn = thread.slice(thread.findLastIndex((m) => m.role === 'user') + 1); const results = turn .filter((m) => m.toolCall?.name === 'cubeSqlApi' && m.toolCall.result) .map((m) => JSON.parse(m.toolCall.result)) .filter((r) => !r.error); const answers = results.some((r) => r.purpose) ? results.filter((r) => r.purpose === 'answer') : results.slice(-1); ``` #### Loading all results `data` holds at most **100 rows**: the rows the agent reads to write its answer. When `truncated` is `true`, the query returned `totalRows` rows in total. To get every row, run the result's `sqlQuery` through the SQL API's [`/v1/cubesql` endpoint][ref-cubesql] as the same user. Your application gets the full result, the agent's context stays small, and the user's row-level security still applies. `sqlQuery` keeps the `LIMIT` the agent wrote, e.g. `LIMIT 5000`, so `totalRows` never exceeds it. To fetch more, raise the `LIMIT` before running the query; the deployment's [row limit][ref-row-limit] still applies. Period comparison columns are not part of `sqlQuery`, so the SQL API returns the rows without them. With API key authentication, if you set `sessionSettings.timezone`, pass the same value as `timezone` to `/v1/cubesql`. Find `DEPLOYMENT_URL` under the deployment's **Settings → API credentials**, e.g. `https://{deployment}.{region}.cubecloudapp.dev`. If you call the Chat API with a [Cube token](#cube-token-authentication), send the same token to the SQL API: ```javascript const result = JSON.parse(message.toolCall.result); const response = await fetch(`${DEPLOYMENT_URL}/cubejs-api/v1/cubesql`, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: CUBE_TOKEN }, body: JSON.stringify({ query: result.sqlQuery }), }); ``` The response is newline-delimited JSON, parsed as in `loadAllRows` in the **API key authentication** tab. With an [API key](#api-key-authentication), first get a Cube API token for the same user. Call [Generate Session][ref-generate-session] with the same API key and the same `externalId` or `internalId`, `email`, `userAttributes`, `groups` and `securityContext` you pass in `sessionSettings`, so the token resolves to the same user and access rules. POST the `sessionId` to [`/api/v1/embed/session/token`][ref-session-token]. A session id is single-use and expires 5 minutes after it is created. POST to [`/api/v1/deployments/{deploymentId}/token`][ref-deployment-token] with `Authorization: Bearer `. The `cubeApiToken` it returns carries the user's security context. `expiresIn` (60–86400 seconds) sets its lifetime. POST `sqlQuery` to `{DEPLOYMENT_URL}/cubejs-api/v1/cubesql` with `Authorization: `. ```javascript const CUBE_URL = 'https://{accountName}.cubecloud.dev'; const DEPLOYMENT_URL = 'https://{deployment}.{region}.cubecloudapp.dev'; const DEPLOYMENT_ID = 1; async function postJson(url, body, headers = {}) { const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', ...headers }, body: JSON.stringify(body), }); if (!response.ok) { throw new Error(`${url} returned ${response.status}: ${await response.text()}`); } return response; } async function getCubeApiToken({ externalId, internalId, email, userAttributes, groups, securityContext, }) { const session = await postJson( `${CUBE_URL}/api/v1/embed/generate-session`, { deploymentId: DEPLOYMENT_ID, externalId, internalId, email, userAttributes, groups, securityContext, }, { Authorization: `Api-Key ${API_KEY}` } ); const { sessionId } = await session.json(); const embed = await postJson(`${CUBE_URL}/api/v1/embed/session/token`, { sessionId }); const { token } = await embed.json(); const cube = await postJson( `${CUBE_URL}/api/v1/deployments/${DEPLOYMENT_ID}/token`, { expiresIn: 3600 }, { Authorization: `Bearer ${token}` } ); const { cubeApiToken } = await cube.json(); return cubeApiToken; } // The SQL API answers with newline-delimited JSON: a schema line, then chunks of rows. // A failed query still returns 200, with an `error` line instead. async function loadAllRows(sqlQuery, cubeApiToken, timezone) { const response = await postJson( `${DEPLOYMENT_URL}/cubejs-api/v1/cubesql`, { query: sqlQuery, timezone }, { Authorization: cubeApiToken } ); const lines = (await response.text()) .split('\n') .filter(Boolean) .map((line) => JSON.parse(line)); const failed = lines.find((line) => line.error); if (failed) { throw new Error(`SQL API error: ${failed.error}`); } const [header, ...chunks] = lines; return { schema: header.schema, data: chunks.flatMap((chunk) => chunk.data) }; } // `sessionSettings` is the object you sent to the Chat API. const result = JSON.parse(message.toolCall.result); if (result.truncated) { // Cache the token per user for its lifetime rather than minting one per result. const cubeApiToken = await getCubeApiToken(sessionSettings); const { schema, data } = await loadAllRows( result.sqlQuery, cubeApiToken, sessionSettings.timezone ); } ``` #### Displaying charts The `cubeSqlApi` tool call returns `vegaSpec` that can be used to display data. Note that it doesn't contain data. You need to use the data from `toolCall.result.data`. #### Styling charts When rendering Vega charts, you can apply custom styling to match the look and feel of your application. This includes adjusting colors, fonts, and other visual elements. Here's a configuration example that mimics Cube's default styling: ```json { // Your Vega configuration "config": { "background": "#ffffff", "padding": 16, "view": { "stroke": "transparent" }, "axis": { "domainColor": "#E0E0E0", "gridColor": "#F5F5F5", "grid": true, "labelFont": "Inter, sans-serif", "labelFontSize": 12, "labelColor": "#43436B", "titleFont": "Inter, sans-serif", "titleFontSize": 12, "titleColor": "#43436B", "titlePadding": 8 }, "numberFormat": "s", "timeFormat": "%Y-%m", "format": { "number": { "format": "s", "formatType": "number" }, "time": { "format": "%Y-%m", "formatType": "time" } }, "legend": { "labelFont": "Inter, sans-serif", "titleFont": "Inter, sans-serif", "labelColor": "#43436B", "titleColor": "#43436B", "labelFontSize": 12, "titleFontSize": 12, "titlePadding": 8, "padding": 8 }, "line": { "strokeWidth": 3, "strokeCap": "round", "point": true }, "text": { "color": "#43436B" }, "point": { "filled": true, "size": 60 }, "range": { "category": [ "#4E79A7", "#F28E2B", "#E15759", "#76B7B2", "#59A14F", "#EDC948", "#B07AA1", "#FF9DA7", "#9C755F", "#BAB0AC" ], "heatmap": [ "#eff6ff", "#1e40af" ] }, "scale": { "band": { "padding": 0.1, "round": true }, "linear": { "nice": true, "zero": true }, "ordinal": { "type": "band", "padding": 0.1 }, "time": { "type": "utc", "nice": true }, "log": { "base": 10, "domain": { "data": "table", "field": "x" }, "range": { "data": "table", "field": "y" } }, "range": [ "#4E79A7", "#F28E2B" ] } } } ``` #### Error Handling When a tool encounters an error, the result field contains structured error information as a JSON string: **Standard Error Format:** When an error occurs, the `result` property of the toolCall will contain an `error` property. ```json { "toolCall": { "name": "cubeMeta", "input": "{\"searchQuery\":\"opportunities deals\"}", "result": "{\n \"error\": \"Error: BadRequestError: Bad branch\"\n}" }, "isInProcess": false } ``` ## Abort Endpoint The Abort endpoint stops an in-progress chat stream. This is useful when the user cancels a request or navigates away while the agent is still generating a response. ### Endpoint **POST** ```text https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/abort https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId}/chat/abort ``` The abort URL is derived from the Chat API URL by replacing `/stream-chat-state` with `/abort` — for whichever form, agent or deployment, you used to start the stream. ### Authentication Supports the same authentication methods as the Chat API: an [API key](#api-key-authentication) or, when enabled for your deployment, a [Cube token](#cube-token-authentication). As with `stream-chat-state`, the `/deployments/{deploymentId}/…` form accepts only a Cube token. ### Request Body - **`chatId`** (string, required): The chat thread ID to abort. This must match the `chatId` of an active or recently completed chat session. - **`sessionSettings`** (object): Same session settings as `stream-chat-state` to authenticate the request. - **`externalId`** (string): Unique identifier for the external user. ### Response - **`204 No Content`**: Chat streaming was aborted successfully. - **`403 Forbidden`**: The authenticated user does not own the specified chat thread. - **`404 Not Found`**: The specified `chatId` does not exist. The abort endpoint answers `204 No Content` as soon as the abort is published; the response has no body. The aborted `stream-chat-state` request itself does not fail with an HTTP error — the streaming response already returned `200 OK` when the stream opened. Instead, that stream emits a terminal frame before it closes: ```json { "id": "__aborted__", "type": "abort", "code": "chat_aborted", "error": "Chat streaming was aborted before the agent finished responding" } ``` Its presence means the content received is partial. Scan the stream for it rather than checking only the last line — the run winds down concurrently, so a late message, the `__state__` snapshot and the `__usage__` frame can still follow it. Calling the abort endpoint again, or on a finished chat, also answers `204`. ### Code Examples ```python title="Python" Python import requests CHAT_API_URL = "YOUR_CHAT_API_URL" ABORT_URL = CHAT_API_URL.replace("/stream-chat-state", "/abort") API_KEY = "YOUR_API_KEY" response = requests.post( ABORT_URL, headers={ "Content-Type": "application/json", "Authorization": f"Api-Key {API_KEY}" }, json={ "chatId": "CHAT_ID_TO_ABORT", "sessionSettings": { "externalId": "user@example.com" } } ) if response.status_code == 204: print("Chat streaming aborted successfully") ``` ```bash title="Bash" cURL # Derive the abort URL from your Chat API URL by replacing /stream-chat-state with /abort ABORT_URL="${CHAT_API_URL/stream-chat-state/abort}" curl -X POST "$ABORT_URL" \ -H "Content-Type: application/json" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -d '{ "chatId": "CHAT_ID_TO_ABORT", "sessionSettings": { "externalId": "user@example.com" } }' ``` ```javascript title="JavaScript" JavaScript const CHAT_API_URL = 'YOUR_CHAT_API_URL'; const ABORT_URL = CHAT_API_URL.replace(/\/stream-chat-state$/, '/abort'); const API_KEY = 'YOUR_API_KEY'; const response = await fetch(ABORT_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Api-Key ${API_KEY}` }, body: JSON.stringify({ chatId: 'CHAT_ID_TO_ABORT', sessionSettings: { externalId: 'user@example.com' } }) }); if (response.status === 204) { console.log('Chat streaming aborted successfully'); } ``` ## Code Examples ```python title="Python" Python import requests import json # Copy the Chat API URL from your agent settings (Admin → Agents → Chat API URL field) CHAT_API_URL = "YOUR_CHAT_API_URL" API_KEY = "YOUR_API_KEY" headers = { "Content-Type": "application/json", "Authorization": f"Api-Key {API_KEY}" } data = { "input": "What are our top performing products?", "sessionSettings": { "externalId": "user@example.com", "email": "user@example.com", # optional "userAttributes": [ # optional { "name": "city", "value": "San Francisco" } ] } } response = requests.post(CHAT_API_URL, headers=headers, json=data, stream=True) for line in response.iter_lines(): if line: message = json.loads(line.decode('utf-8')) print("Received:", message) ``` ```bash title="Bash" cURL # Copy YOUR_CHAT_API_URL from your agent settings (Admin → Agents → Chat API URL field) curl -X POST "YOUR_CHAT_API_URL" \ -H "Content-Type: application/json" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -d '{ "input": "Show me revenue trends for the last 6 months", "sessionSettings": { "externalId": "user@example.com" } }' ``` ```javascript title="JavaScript" JavaScript // Copy the Chat API URL from your agent settings (Admin → Agents → Chat API URL field) const CHAT_API_URL = 'YOUR_CHAT_API_URL'; const API_KEY = 'YOUR_API_KEY'; const response = await fetch( CHAT_API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Api-Key ${API_KEY}` }, body: JSON.stringify({ input: 'Hello, how can you help me analyze our data?', sessionSettings: { externalId: 'user@example.com', email: 'user@example.com', // optional userAttributes: [ // optional { name: 'city', value: 'San Francisco' } ] } }) } ); // Handle streaming response const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); const lines = chunk.trim().split('\n'); lines.forEach(line => { if (line) { const message = JSON.parse(line); console.log('Received:', message); // Handle different message types if (message.role === 'assistant' && message.content) { updateChatUI(message); } } }); } ``` ## Error Handling - **204 No Content**: (Abort endpoint only) Chat streaming was aborted successfully. - **400 Bad Request**: Invalid request body or parameters. Check required fields and data types. - **Authentication errors**: Returned as a JSON-RPC error object in an HTTP 200 response. Verify your API key is correct and has the necessary permissions. For Cube token authentication, verify the token is valid for the agent's deployment, identifies a user via `externalId` (or `sub`), and carries the `chat` scope. - **403 Forbidden**: (Abort endpoint only) The authenticated user does not own the specified chat thread. - **404 Not Found**: Agent, tenant, or chat thread not found. Verify the Chat API URL from your agent settings and the `chatId`. - **500 Internal Server Error**: Server processing error. Contact support if the issue persists. [ref-api-keys]: /admin/account-billing/api-keys [ref-jwt-auth]: /embedding/authentication/jwt [ref-config-check-auth]: /reference/configuration/config#check_auth [ref-headless-embedding]: /embedding#headless-embedding [ref-cubesql]: /reference/core-data-apis/rest-api/reference#base_path/v1/cubesql [ref-row-limit]: /reference/core-data-apis/queries#row-limit [ref-mcp-period-comparisons]: /docs/integrations/mcp-server#period-comparisons [ref-generate-session]: /reference/embed-apis/generate-session [ref-session-token]: /api-reference/embed/exchange-a-session-for-an-embed-token [ref-deployment-token]: /api-reference/deployments/deployment-token