Skip to main content
GET
/
v1
/
chats
/
{chat_id}
Get Chat
curl --request GET \
  --url https://api.cuadra.ai/v1/chats/{chat_id} \
  --header 'Authorization: Bearer <token>'
{
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "organizationId": "<string>",
  "id": "<string>",
  "modelId": "<string>",
  "createdBy": "<string>",
  "title": "Product Support Chat",
  "systemPrompt": "You are a helpful customer support assistant.",
  "metadata": "<unknown>",
  "status": "generating",
  "lastError": "Stream interrupted (client disconnect or network error)",
  "lastErrorAt": "2023-11-07T05:31:56Z",
  "model": {
    "contextWindow": 128000,
    "createdAt": "2025-09-08T06:33:19Z",
    "creditMultiplier": 2,
    "description": "Advanced language model for complex tasks",
    "displayName": "large-model Omni",
    "enabled": true,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "isRecommended": true,
    "isSystemModel": false,
    "lifecycleState": "active",
    "maxTokensPerRequest": 4096,
    "metadata": {},
    "modelName": "large-modelo",
    "provider": "provider-a",
    "supportsStreaming": true,
    "updatedAt": "2025-09-08T06:33:19Z"
  },
  "messages": [
    {
      "role": "user",
      "id": "<string>",
      "chatId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "content": "What is the weather in San Francisco?",
      "tokenCount": 150,
      "cost": "0.0015",
      "responseTimeMs": 1250,
      "metadata": {
        "source": "api"
      },
      "toolCallId": "call_abc123",
      "toolCalls": [
        {
          "id": "<string>",
          "function": {
            "name": "<string>",
            "arguments": "<string>"
          },
          "type": "function"
        }
      ],
      "files": [
        {
          "id": "<string>",
          "filename": "<string>",
          "contentType": "image/png",
          "sizeBytes": 204800,
          "url": "/v1/files/file_abc123/content"
        }
      ]
    }
  ],
  "documentsCount": 0,
  "visibility": "private",
  "sharedWith": [
    "user_123",
    "user_456"
  ],
  "deletedAt": "2023-11-07T05:31:56Z",
  "deletedBy": "<string>",
  "source": "api",
  "sourceDetail": "<string>",
  "ephemeral": false,
  "ephemeralExpiresAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

JWT token from Stytch B2B authentication (magic link, SSO, or M2M)

Path Parameters

​
chat_id
string
required

Chat ID

Example:

"chat_abc123"

Query Parameters

​
expand[]
string[] | null

List of related objects to expand in the response. Example: ?expand[]=model&expand[]=versions

Example:
["model"]

Response

Successful Response

Chat response with full details.

​
createdAt
string<date-time>
required

Timestamp when the resource was created

Example:

"2024-01-15T10:30:00Z"

​
updatedAt
string<date-time>
required

Timestamp when the resource was last updated

Example:

"2024-01-15T14:45:00Z"

​
organizationId
string
required

Organization ID for tenant isolation

Required string length: 1 - 64
Example:

"org_abc123"

​
id
string
required

Unique chat identifier

Example:

"chat_abc123"

​
modelId
string
required

Identifier of the AI model used for this chat.

Example:

"model_large-model"

​
createdBy
string
required

ID of the user who created this chat

Example:

"user_xyz789"

​
title
string | null

Chat title

Maximum string length: 500
Example:

"Product Support Chat"

​
systemPrompt
string | null

System-level instructions for the AI model.

Example:

"You are a helpful customer support assistant."

​
metadata
any
​
status
enum<string> | null

Operational status of the chat. 'generating' indicates a background stream is actively running (poll again). 'error' indicates the last stream was interrupted or failed. null indicates the chat is in a normal, idle state.

Available options:
generating,
error
Example:

"generating"

​
lastError
string | null

Human-readable description of the last error, if status is 'error'.

Example:

"Stream interrupted (client disconnect or network error)"

​
lastErrorAt
string<date-time> | null

Timestamp of the last error, if status is 'error'.

​
model
ModelOut · object

Full model object (included when expanded with ?expand[]=model)

Example:
{
  "contextWindow": 128000,
  "createdAt": "2025-09-08T06:33:19Z",
  "creditMultiplier": 2,
  "description": "Advanced language model for complex tasks",
  "displayName": "large-model Omni",
  "enabled": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "isRecommended": true,
  "isSystemModel": false,
  "lifecycleState": "active",
  "maxTokensPerRequest": 4096,
  "metadata": {},
  "modelName": "large-modelo",
  "provider": "provider-a",
  "supportsStreaming": true,
  "updatedAt": "2025-09-08T06:33:19Z"
}
​
messages
MessageOut · object[]

Messages in this chat

​
documentsCount
integer
default:0

Total number of documents associated with the chat.

Required range: x >= 0
Example:

3

​
visibility
enum<string>
default:private

Chat visibility level

Available options:
private,
organization,
shared
Example:

"private"

​
sharedWith
string[] | null

List of user IDs this chat is shared with

Example:
["user_123", "user_456"]
​
deletedAt
string<date-time> | null

Timestamp when the chat was soft-deleted

​
deletedBy
string | null

ID of the user who deleted this chat

​
source
string
default:api

Request origin: api, m2m, connector

​
sourceDetail
string | null

Specific source: dashboard, slack, google_drive, etc.

​
ephemeral
boolean
default:false

When true the chat has a finite TTL and will be automatically deleted once ephemeral_expires_at is reached.

​
ephemeralExpiresAt
string<date-time> | null

UTC timestamp at which this ephemeral chat will be auto-deleted. Null for non-ephemeral chats.