Skip to content
Clear Street Clear Street
Get started
API Reference
V1
Omni AI
Responses

Get Response By ID

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

Poll a response for assistant output.

Returns the current snapshot of an in-progress or completed response. While the status is queued or running, the content may be partial and may include thinking parts. Poll this endpoint periodically until the status reaches a terminal value (succeeded, failed, or canceled).

Once terminal, the finalized assistant message is available in thread history via GET /omni-ai/threads/{thread_id}/messages.

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

Account ID for the request

formatint64
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 }

Dynamic response content container. May include thinking parts.

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

Text content part.

type: "text"
ContentPartThinkingPayload { thoughts }

Thinking content part shown on dynamic response polling.

type: "thinking"
ContentPartStructuredActionPayload { action, action_id }

Structured action content part.

type: "structured_action"
ContentPartChartPayload { payload }

Chart payload content part.

type: "chart"
ContentPartSuggestedActionsPayload { payload }

Suggested actions payload content part.

type: "suggested_actions"
ContentPartCustomPayload { payload }

Escape-hatch custom payload content part.

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

Shared sanitized error payload.

code: string
message: string
details: optional unknown
output_message_id: optional string

Get Response By ID

curl https://api.clearstreet.com/v1/omni-ai/responses/$RESPONSE_ID \
    -H "Authorization: Bearer $API_KEY"
{
  "data": {
    "content": {
      "parts": [
        {
          "text": "<ticker>AAPL</ticker> is currently trading at ...",
          "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": "Failed to deserialize query string: missing field `account_id`"
  },
  "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": "Response not found"
  },
  "metadata": {
    "request_id": "e232b453-b4a9-4594-a56f-85c1e62ef40f"
  }
}
Returns Examples
{
  "data": {
    "content": {
      "parts": [
        {
          "text": "<ticker>AAPL</ticker> is currently trading at ...",
          "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": "Failed to deserialize query string: missing field `account_id`"
  },
  "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": "Response not found"
  },
  "metadata": {
    "request_id": "e232b453-b4a9-4594-a56f-85c1e62ef40f"
  }
}