Skip to content
Clear Street Clear Street Clear Street
Start Trading
API Reference
V1
Omni AI
Responses

Get Response By ID

GET/v1/omni-ai/responses/{response_id}

Poll the current snapshot of an in-progress or completed assistant response. While its status is queued or running, content may be partial and include thinking parts. Continue polling until it becomes succeeded, failed, or canceled.

Once terminal, the finalized message is available through GET /omni-ai/threads/{thread_id}/messages. Authorization uses the current parent thread account, including for responses created before the account link.

Path ParametersExpand Collapse
response_id: string
Query ParametersExpand Collapse
account_id: optional number

Lists only conversations for this account, or unlinked conversations when omitted. Other reads authorize the resource’s linked account. Omit when no account is selected; empty values and the string null are invalid.

formatint64
minimum1
ReturnsExpand Collapse
data: Response { id, status, thread_id, 4 more }

Dynamic pollable response.

id: string

Dynamic lifecycle status for a pollable response.

One of the following:
"queued"
"running"
"succeeded"
"failed"
"canceled"
thread_id: string
user_message_id: string
content: optional ResponseContent { parts }

When a null/undefined value is observed, it indicates that there is no available data.

parts: array of ResponseContentPart
One of the following:
ContentPartText = ContentPartTextPayload { text }

Text content part.

type: "text"
ContentPartThinking = ContentPartThinkingPayload { thoughts }

Thinking content part shown on dynamic response polling.

type: "thinking"
ContentPartStructuredAction = ContentPartStructuredActionPayload { action, action_id, clicked, 2 more }

Structured action content part.

type: "structured_action"
ContentPartChart = ContentPartChartPayload { payload }

Chart payload content part.

type: "chart"
ContentPartSuggestedActions = ContentPartSuggestedActionsPayload { payload }

Suggested actions payload content part.

type: "suggested_actions"
ContentPartCustom = ContentPartCustomPayload { payload }

Escape-hatch custom payload content part.

type: "custom"
error: optional ErrorStatus { code, message, details }

When a null/undefined value is observed, it indicates it does not apply.

code: string
message: string
details: optional unknown

When a null/undefined value is observed, it indicates it does not apply.

output_message_id: optional string

When a null/undefined value is observed, it indicates it does not apply.

formatuuid

Get Response By ID

curl https://api.clearstreet.com/v1/omni-ai/responses/$RESPONSE_ID \
    -H "Authorization: Bearer $API_KEY"
{
  "data": {
    "content": {
      "parts": [
        {
          "text": "[AAPL](ticker:AAPL) is currently trading at $192.35, up 1.2% on the day.",
          "type": "text"
        },
        {
          "thoughts": [
            "Fetching current market data for AAPL..."
          ],
          "type": "thinking"
        }
      ]
    },
    "id": "019dbafd-db54-7523-a412-ec9195cc5d99",
    "output_message_id": "019dbafd-db61-73a0-8bd9-d4034d132f81",
    "status": "succeeded",
    "thread_id": "019dbafd-db54-7523-a412-ec8a292246ad",
    "user_message_id": "019dbafd-db56-78a2-8a91-d54a39f44174"
  },
  "metadata": {
    "request_id": "abc16101-2cbc-475a-84ef-98c8c588dcbb"
  }
}
{
  "error": {
    "code": 400,
    "message": "account_id must be positive"
  },
  "metadata": {
    "request_id": "f5acc83c-57e7-4966-a699-17a9b552199b"
  }
}
{
  "error": {
    "code": 403,
    "message": "The caller does not have permission to execute the specified operation"
  },
  "metadata": {
    "request_id": "b2d2d764-61f9-41c4-91c8-dd4366fc35c8"
  }
}
{
  "error": {
    "code": 404,
    "message": "Resource not found"
  },
  "metadata": {
    "request_id": "e232b453-b4a9-4594-a56f-85c1e62ef40f"
  }
}
Returns Examples
{
  "data": {
    "content": {
      "parts": [
        {
          "text": "[AAPL](ticker:AAPL) is currently trading at $192.35, up 1.2% on the day.",
          "type": "text"
        },
        {
          "thoughts": [
            "Fetching current market data for AAPL..."
          ],
          "type": "thinking"
        }
      ]
    },
    "id": "019dbafd-db54-7523-a412-ec9195cc5d99",
    "output_message_id": "019dbafd-db61-73a0-8bd9-d4034d132f81",
    "status": "succeeded",
    "thread_id": "019dbafd-db54-7523-a412-ec8a292246ad",
    "user_message_id": "019dbafd-db56-78a2-8a91-d54a39f44174"
  },
  "metadata": {
    "request_id": "abc16101-2cbc-475a-84ef-98c8c588dcbb"
  }
}
{
  "error": {
    "code": 400,
    "message": "account_id must be positive"
  },
  "metadata": {
    "request_id": "f5acc83c-57e7-4966-a699-17a9b552199b"
  }
}
{
  "error": {
    "code": 403,
    "message": "The caller does not have permission to execute the specified operation"
  },
  "metadata": {
    "request_id": "b2d2d764-61f9-41c4-91c8-dd4366fc35c8"
  }
}
{
  "error": {
    "code": 404,
    "message": "Resource not found"
  },
  "metadata": {
    "request_id": "e232b453-b4a9-4594-a56f-85c1e62ef40f"
  }
}