Omni AI

Omni is Clear Street’s proprietary financial copilot for the Clear Street trading platform. It can help you with:

• Market research - Look up stocks, analyze price movements, find news and catalysts
• Portfolio insights - View your positions, balances, and performance history
• Trade execution - Place orders for US equities, ETFs, and equity options
• Options analysis - Price options, calculate Greeks, and estimate probabilities
• Order management - Query, track, modify, and cancel your orders

Omni has access to real-time market data, your account information, and research tools to help you make informed trading decisions.The following section covers the available endpoints.

Entitlements

Before Omni can provide personalized portfolio and trade insight, you need to grant Omni access to your account data via an entitlement agreement. Note that this still does not allow Omni to take any actions on your behalf without confirmation. Omni’s list of entitlement agreements can be found via the GET /v1/omni-ai/entitlement-agreements. If you want to provide Omni access you can take the agreement_id and entitlement_codes and pass those along with the account id in the body of POST /v1/omni-ai/entitlements request as shown below.

{
  "agreement_id": "01JZ0000000000000000000000",
  "entitlement_codes": ["omni.account_data"],
  "account_ids": ["{account_id}", "{account_id}"]
}

If done properly you will see the relevant agreements and entitlements returned back in the response of GET /v1/omni-ai/entitlements

Note that you can remove the entitlement at any time by using the DELETE /v1/omni-ai/entitlements/{entitlement_id}

Conversations with Omni

There are 3 key terms to understand when interacting with Omni APIs which are threads, messages and responses.

• Threads - holds the full conversation history and has a title and timestamps. It does not contain content directly but rather is the container that groups messages together.
• Messages - A message is a finalized immutable record in a thread. It can be a USER message or an ASSISTANT (produced by Omni) message. A message only exists here after a terminal state is reached — you cannot see a message while Omni is still generating it.
• Responses - The live, poll-able view into Omni’s response to a user’s message. It has a lifecycle status like queued, running, succeeded, failed, canceled, steered, or merged. While it is being generated, it may include partial text and thinking content. Once it reaches a terminal state, the assistant output becomes available as a finalized message in the thread.

In summary, the Response is what you watch while waiting for Omni to produce a finalized message. The Message is the permanent record you read back when replaying history and messages are contained within threads. Next, let’s dive into a typical Omni workflow.

Omni Workflow

1. User creates a thread with a prompt via create threads endpoint
2. API response returns thread_id, user_message_id, user_message_seq, and response_id
   1. A reference to a message carries that message’s seq: user_message_seq comes with user_message_id, and a response’s output_message_seq comes with its output_message_id. Use the seq to place a message in the thread’s message list before the list shows it.
3. User polls the thread response endpoint GET /v1/omni-ai/threads/{thread_id}/response while the thread is open. It returns the running response, or else the next queued response, and returns data: null once the thread is idle. When the polled response id changes or data is null, refresh the thread’s messages.
   1. To follow one known response, the response by id endpoint returns it by response_id.
   2. Some answers start without a request. Omni can hand a question to a subagent that works in the background and answer when it finishes, even after the thread went idle. That response has no user_message_id: it presents a background result, such as a subagent’s report, rather than answering a message. Keep polling the thread response while the thread is open so these answers appear, and refresh messages when they end.
4. When a response succeeds, Omni’s answer appears as a finalized message in that thread. As long as a response has not reached a terminal state you can cancel it with the cancel response endpoint. Canceling the running response (Stop) also cancels the queued responses for the messages sent after it. Canceling a queued response (withdraw) cancels only that response; the running response and other queued responses continue. Canceling a response that ended steered or merged follows its continued_in_response_id and stops the response that continues its work, as Stop does. Each canceled response leaves a finalized assistant message with outcome canceled.
5. User can read messages in a thread using the get messages endpoint
   1. For any of the messages marked with a role of ASSISTANT (Omni’s messages), users have the ability to provide feedback using the submit feedback endpoint
6. User can create a new thread or continue a conversation using the create message endpoint, including while a response is still running. A message sent while another response is active gets a queued response, and steers the running response at its next safe point:
   1. The running response ends steered if it showed text, or merged if it showed no text. The response for the newest message continues the work and answers all messages sent so far. Earlier queued responses that it answers also end merged.
   2. When a response ends steered or merged, poll the response in its continued_in_response_id at once. That response continues the work.
   3. Some requests, such as research, do not steer. Their responses, and the responses for messages sent after them, start in order after the earlier responses end.
7. Additionally a user can navigate to another thread by looking up all threads using get threads endpoint GET /v1/omni-ai/threads and getting the messages for that thread

Defining Capabilities

When you create a new thread or a new message as part of the request body a user is able to define which types of structured output Omni is permitted to emit in a response. This is done through the capabilities field. This is important to note because Omni can return more than just plain text and capabilities keep Omni from sending actions the client cannot render or safely support. Below is a list of current capabilities Omni supports:

Capability	What it unlocks
PREFILL_ORDER	Omni may suggest order tickets — new orders, modifications, or cancellations — for the user to review and confirm
OPEN_CHART	Omni may emit inline charts and open_chart actions directing the UI to display a symbol chart
OPEN_SCREENER	Omni may emit open_screener actions with pre-configured filters, sort, and field selection
OPEN_ENTITLEMENT_CONSENT	Omni may prompt the user to grant account-data access when it needs consent to proceed

For API users, the practical rule is:

• If you only want text answers, omit capabilities or send an empty array.
• If your app can render charts, send OPEN_CHART.
• If your app can show a user-reviewed order ticket, send PREFILL_ORDER.
• If your app supports saved/symbol screeners, send OPEN_SCREENER.
• If your app can present Omni account-data consent, send OPEN_ENTITLEMENT_CONSENT.

Response Status Definitions

Status	Description	Terminal
Queued	Accepted, waiting for earlier responses in the thread or for Omni’s work to start.	No
Running	Omni’s work is in progress. Content may be partial.	No
Succeeded	Omni’s response completed successfully	Yes
Failed	Omni’s response failed. Check error.	Yes
Canceled	Omni’s response was canceled	Yes
Steered	Ended as written after a newer user message. A later response continues the work.	Yes
Merged	Ended without text. A later response answers its message.	Yes

Treat an unknown status as terminal. Once terminal, the finalized assistant message is available through the message endpoints.

Messages Outcome Definitions

Outcome	Description
Completed	Finalized successfully
Errored	Failed during execution
Canceled	Canceled before completion
Steered	Complete as written; the user sent a newer message before it finished
Merged	No content; a later answer covers this turn. Hide this message.

Additional endpoints

Action	Method	Path	Description
Get Message by ID	GET	/v1/omni-ai/messages/{message_id}	Getting a specific message by id
Get Thread by ID	GET	/v1/omni-ai/threads/{thread_id}	Getting a specific thread by id, note it does not include the messages

• Omni AI is provided by Clear Street Technology LLC.

---