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, canceled, steered, or merged. Treat an unknown status as terminal. On steered or merged, poll the response in continued_in_response_id at once: it continues the work.

Once terminal, the finalized message is available through GET /omni-ai/threads/{thread_id}/messages; refresh messages when a response ends. 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, 7 more }

Dynamic pollable response.

id: string

Dynamic lifecycle status for a pollable response.

succeeded, failed, canceled, steered and merged are terminal. steered: the response ended as written because the user sent a newer message, and a later response in the thread continues the work. merged: the response ended without text, and a later response answers its message. Treat an unknown status as terminal.

One of the following:
"queued"
"running"
"succeeded"
"failed"
"canceled"
"steered"
"merged"
thread_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"
continued_in_response_id: optional string

The response that continues the work of this response. Present only when status is steered or merged. Follow it to keep showing the answer. To stop that work, cancel it, or cancel this response: the server follows the link. When a null/undefined value is observed, it indicates it does not apply.

formatuuid
error: optional ErrorStatus { code, message, details }

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

code: string

FAILED, or execution_interrupted when Omni lost the worker running the response; partial content is kept; send the message again.

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
output_message_seq: optional number

The seq the output message has in the thread’s message list. Present once the output message exists. Omitted while the response is queued. Use it to place a response that is still in progress among the listed messages. When a null/undefined value is observed, it indicates it does not apply.

formatint64
user_message_id: optional string

The user message this response answers. Omitted when the response presents a background result, such as a subagent’s report, and answers no user message; its output message then appears in the thread without a preceding request. When a null/undefined value is observed, it indicates it does not apply.

formatuuid
user_message_seq: optional number

The seq the user message has in the thread’s message list. Present exactly when user_message_id is present. Use it to place the sent prompt among the listed messages before a list refresh includes it. When a null/undefined value is observed, it indicates it does not apply.

formatint64

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",
    "output_message_seq": 2,
    "status": "succeeded",
    "thread_id": "019dbafd-db54-7523-a412-ec8a292246ad",
    "user_message_id": "019dbafd-db56-78a2-8a91-d54a39f44174",
    "user_message_seq": 1
  },
  "metadata": {
    "request_id": "abc16101-2cbc-475a-84ef-98c8c588dcbb"
  }
}
{
  "data": {
    "content": {
      "parts": [
        {
          "text": "[AAPL](ticker:AAPL) is currently trading at $192.35. Checking the latest earnings next.",
          "type": "text"
        }
      ]
    },
    "continued_in_response_id": "019dbafe-2c41-7b8e-9d3a-61f0c2a4b7e5",
    "id": "019dbafd-db54-7523-a412-ec9195cc5d99",
    "output_message_id": "019dbafd-db61-73a0-8bd9-d4034d132f81",
    "output_message_seq": 2,
    "status": "steered",
    "thread_id": "019dbafd-db54-7523-a412-ec8a292246ad",
    "user_message_id": "019dbafd-db56-78a2-8a91-d54a39f44174",
    "user_message_seq": 1
  },
  "metadata": {
    "request_id": "5f2b8c1e-7d3a-4e9b-a6c4-0b1d2e3f4a5b"
  }
}
{
  "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",
    "output_message_seq": 2,
    "status": "succeeded",
    "thread_id": "019dbafd-db54-7523-a412-ec8a292246ad",
    "user_message_id": "019dbafd-db56-78a2-8a91-d54a39f44174",
    "user_message_seq": 1
  },
  "metadata": {
    "request_id": "abc16101-2cbc-475a-84ef-98c8c588dcbb"
  }
}
{
  "data": {
    "content": {
      "parts": [
        {
          "text": "[AAPL](ticker:AAPL) is currently trading at $192.35. Checking the latest earnings next.",
          "type": "text"
        }
      ]
    },
    "continued_in_response_id": "019dbafe-2c41-7b8e-9d3a-61f0c2a4b7e5",
    "id": "019dbafd-db54-7523-a412-ec9195cc5d99",
    "output_message_id": "019dbafd-db61-73a0-8bd9-d4034d132f81",
    "output_message_seq": 2,
    "status": "steered",
    "thread_id": "019dbafd-db54-7523-a412-ec8a292246ad",
    "user_message_id": "019dbafd-db56-78a2-8a91-d54a39f44174",
    "user_message_seq": 1
  },
  "metadata": {
    "request_id": "5f2b8c1e-7d3a-4e9b-a6c4-0b1d2e3f4a5b"
  }
}
{
  "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"
  }
}