Skip to content
Clear Street Clear Street Clear Street
Start Trading

Changelog

Notable additions and changes to the Clear Street Trading API.

Clearer order rejection reasons

Orders rejected by pre-trade risk checks now report plain-English reasons — for example, “Insufficient buying power” instead of “Buying Power: required > available”. The machine-readable codes were also revised: SUB_PENNY is now INVALID_TICK_SIZE, SSR_UPTICK was retired, and LIQUIDATION_ONLY was split into INSTRUMENT_LIQUIDATION_ONLY and ACCOUNT_LIQUIDATION_ONLY. Avoid matching on the human-readable text.

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/accounts/{account_id}/orders
  • GET /v1/accounts/{account_id}/orders/{order_id}

Event defaults anchored to the next trading day

When listing instrument events on a weekend or US market holiday, the default from/to date window is now resolved against the next trading day rather than the calendar date, so upcoming-event queries made over a weekend cover the next session.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments/events
  • GET /v1/instruments/{instrument_id}/events

Underlier populated for index-option contracts

underlying_instrument_id is now populated on option contracts whose underlier is an index; it was previously null for these contracts.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments/options/contracts

Account-holder details on Get Account

GET /v1/accounts/{account_id} now returns an enriched account object with the account holder’s reference details. Four new fields are included, each nullable and null when the information is not on file or reference data is unavailable:

  • mailing_address — a structured address (line1, line2, city, state, postal_code, country).

  • date_of_birth

  • phone_number

  • country_of_tax_residency

    Existing fields are unchanged; the additions are purely additive.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}

Instrument fields removed; time-in-force locked on replace

Two removals to be aware of:

  • The long-deprecated expiry and strike_price fields (which had been returning null since 2026-06-17) have been removed from the instrument response. Read option contract details from the options endpoints instead.
  • time_in_force has been removed from the replace-order request body. Time in force can no longer be changed when replacing an order — submit a new order if you need a different TIF.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments
  • GET /v1/instruments/{instrument_id}
  • PATCH /v1/accounts/{account_id}/orders/{order_id}

Modify action in Omni prefill orders

Omni AI structured “prefill order” cards can now suggest a modify action (PrefillModifyOrderAction) in addition to the existing new-order and cancel-order actions, letting the assistant propose an amendment to a working order.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/omni-ai/messages/{message_id}
  • GET /v1/omni-ai/threads/{thread_id}/messages

Order and fill instrument fields are now nullable

On order and execution (fill) responses, instrument_id, symbol, and (for orders) instrument_type are now nullable and no longer guaranteed present. They are null when an order or fill has no single resolvable instrument. Code that assumes these fields are always populated should add a null check.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/orders
  • GET /v1/accounts/{account_id}/orders/{order_id}

INDEX security type

INDEX is now a valid value in the security-type enum. It appears on instrument responses and is accepted by the instrument_type filter when listing or cancelling orders.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments
  • GET /v1/accounts/{account_id}/orders
  • DELETE /v1/accounts/{account_id}/orders

Omni entitlements: trading_account_id renamed to account_id

On the Omni AI entitlements endpoint, the trading_account_id query parameter and the matching trading_account_id response field have both been renamed to account_id. Update any requests or response parsing that used the old name.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/omni-ai/entitlements

Annual financials and earnings report timing

Two additions to instrument data:

  • The fiscal-period enum on fundamentals and financial-statement responses now includes ANNUAL (alongside the existing quarterly periods).
  • Earnings entries in instrument events now carry a nullable report_time field with values BMO (before market open) and AMC (after market close).

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments/{instrument_id}/fundamentals
  • GET /v1/instruments/events
  • GET /v1/instruments/{instrument_id}/events

Tradability flag on option contracts

Option contract responses now include a required is_tradable boolean indicating whether the contract is currently tradable.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments/options/contracts

Symbols accepted more widely; market-hours date optional

Quality-of-life improvements to filtering:

  • instrument_ids and underlying_instrument_ids now accept instrument symbols (equity tickers or OSI option symbols) in addition to UUIDs on order, instrument-event, and market-data snapshot lookups.
  • The date parameter on the market-hours calendar is now optional and defaults to today.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/orders
  • GET /v1/instruments/events
  • GET /v1/market-data/snapshot
  • GET /v1/calendars/market-hours

Index-aware market data and fundamentals

Better handling for instruments that don’t have certain data by definition (for example, an index):

  • The daily-summary response gains a required not_applicable boolean that distinguishes “this instrument type has no daily summary” from “data not yet loaded.”
  • The fundamentals endpoint now returns a 400 for instruments whose type has no fundamentals.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/market-data/daily-summary
  • GET /v1/instruments/{instrument_id}/fundamentals

Clearer index snapshots

For index instruments, the market-data snapshot’s last-trade now reports the current index level in price with size always 0 (an index level is computed, not traded).

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/market-data/snapshot

position_effect removed from order submission

The position_effect request field (with its OPEN / CLOSE enum), previously required on options orders, has been removed from order submission. Remove it from your order payloads.

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/accounts/{account_id}/orders

Executions filter renamed to instrument_ids

On the executions endpoint, the instrument_id query parameter has been renamed to instrument_ids and now accepts a comma-separated list of instrument IDs or symbols, returning executions matching any of them.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/executions

Screener field_filter and option position types removed

Two enum/field removals:

  • The deprecated field_filter property has been removed from the screener request and response schemas. Use columns for field selection instead.
  • The option-specific position types LONG_CALL, SHORT_CALL, LONG_PUT, and SHORT_PUT have been removed from the position type enum. Positions now report only LONG or SHORT.

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/screener
  • POST /v1/saved-screeners
  • GET /v1/saved-screeners
  • GET /v1/saved-screeners/{screener_id}
  • PUT /v1/saved-screeners/{screener_id}
  • GET /v1/accounts/{account_id}/positions

One-sided quotes in snapshots

The snapshot quote fields bid, ask, and midpoint are no longer required and may be null — for example, on a one-sided quote where only a bid or only an ask is present.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/market-data/snapshot

Idle Omni threads return 200 instead of 404

Requesting the latest response for an idle thread now returns 200 with data: null rather than 404. A 404 from this endpoint now unambiguously means the thread was not found. If you previously treated 404 as “thread is idle,” switch to checking for a null data.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/omni-ai/threads/{thread_id}/response

Filter accounts by id and name

Listing accounts now supports two optional query filters:

  • account_id — lexicographic prefix match on the decimal account id (e.g. 100 matches 100345 and 100567).

  • account_name — case-insensitive substring match on the account’s full name.

    When both are supplied, an account must match both.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts

Filter orders by order_ids

The order-list endpoint accepts a new order_ids query parameter — a comma-separated set of order IDs — to fetch a specific group of orders in one call.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/orders

Screener

The Trading API now exposes a Screener for querying instruments against fundamental and reference criteria, plus the ability to save and reuse screens.

Running a screen

Section titled “Running a screen”

POST /v1/screener runs a structured screen and returns a columnar row/column result. Requests describe the fields to return (columns), filters (with a rich operator set), sorting, and pagination.

Saved screeners

Section titled “Saved screeners”

Persist a screen and manage it over time:

  • GET /v1/saved-screeners — list your saved screeners
  • POST /v1/saved-screeners — create one
  • GET /v1/saved-screeners/{screener_id} — fetch one
  • PUT /v1/saved-screeners/{screener_id} — replace one
  • DELETE /v1/saved-screeners/{screener_id} — delete one

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/screener
  • GET /v1/saved-screeners
  • POST /v1/saved-screeners
  • GET /v1/saved-screeners/{screener_id}
  • PUT /v1/saved-screeners/{screener_id}
  • DELETE /v1/saved-screeners/{screener_id}

Look up instruments by symbol

The instrument_ids filter on the instruments endpoint now accepts symbols (an equity symbol or an OSI option symbol) in addition to instrument UUIDs. Symbols are resolved server-side, so you no longer need a UUID round-trip to filter by ticker.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments

Instrument expiry/strike_price and screener field_filter

Advance notice of fields being retired:

  • Instrument expiry and strike_price are deprecated and now always return null — read contract details from the options endpoints instead.
  • The screener field_filter request field is deprecated in favor of columns.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments
  • GET /v1/instruments/{instrument_id}
  • GET /v1/instruments/search
  • POST /v1/screener

Live P&L on balances and positions

New profit-and-loss fields, computed in real time:

  • Balances gains three required fields: unrealized_pnl (total unrealized P&L across open positions), daily_pnl (total P&L since start of day), and daily_change (current equity vs. start-of-day equity).
  • Each position gains an optional daily_realized_pnl, and the positions sort_by parameter accepts a new DAILY_REALIZED_PNL value.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/balances
  • GET /v1/accounts/{account_id}/positions

ENGINE_REJECTED status removed

The ENGINE_REJECTED value has been removed from the position-instruction status enum. Instructions that fail pre-venue validation now report status: REJECTED with a rejection_reason. Note that instructions failing pre-acceptance validation (duplicate instruction_id, DNE/CEA on a non-expiry day, insufficient position, or an unresolvable instrument) are never persisted — they appear only in the submission response, not in the instructions list.

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/accounts/{account_id}/positions/instructions
  • GET /v1/accounts/{account_id}/positions/instructions

Per-session buying power on balances

The margin section of the balances response gains two required objects, intraday_details and overnight_details, each exposing that session’s buying_power and an optional margin multiplier.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/balances

Day-trade fields on balances deprecated

Several day-trade fields on the balances response are deprecated and will be removed in a future release:

  • The start-of-day day_trade_buying_power, day_trade_buying_power_usage, day_trade_count, and pattern_day_trader fields.
  • The day_trade_buying_power_usage field on each margin top-contributor entry.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/balances

Smarter option search

Instrument search now matches option contracts by OSI prefix — a root plus a YYMMDD expiry (e.g. AAPL 261217) — and by root-scoped phrases such as AAPL Dec 250 call, in addition to full OSI symbols.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments/search

Richer batch errors, typed deletes, multi-underlier filter

A set of refinements:

  • On position-instruction submissions where every row is rejected, the 400 / 409 / 503 responses now return the full per-row data list (each row carrying its status and rejection_reason) instead of a bare error, and a new 500 response covers an all-rows-rejected internal fault.
  • Delete endpoints now return a typed body (data: null) instead of an untyped empty response.
  • The underlying_instrument_ids order filter now accepts multiple underlier instrument IDs (array) rather than a single value.

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/accounts/{account_id}/positions/instructions
  • DELETE /v1/watchlists/{watchlist_id}
  • DELETE /v1/watchlists/{watchlist_id}/items/{item_id}
  • GET /v1/accounts/{account_id}/orders

Instrument restriction flag and security types removed

Removals to instrument data:

  • The is_restricted field has been removed from instrument and option-contract responses, along with the is_restricted filter on the instruments endpoint and the include_restricted parameter on instrument search.
  • PREFERRED_STOCK and OTHER have been removed from the security-type enum, which is now COMMON_STOCK, OPTION, CASH. This affects the instrument_type order filter and the security-type field on instrument responses.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments
  • GET /v1/instruments/{instrument_id}
  • GET /v1/instruments/search
  • GET /v1/instruments/options/contracts
  • GET /v1/accounts/{account_id}/orders

Option greeks in snapshots

Market-data snapshots for option instruments now include a greeks object with theo_price, iv, delta, gamma, vega, theta, rho, and a timestamp (per-share values). It is null for equities.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/market-data/snapshot

Publicly-traded-partnership flag

Instruments now carry a required is_ptp boolean flagging publicly-traded partnerships (PTP sales are subject to 10% withholding for non-US tax residents). Related filters were added too:

  • is_ptp boolean filter on the instruments endpoint.
  • include_ptp on instrument search (default true; PTP instruments are penalized in ranking when included).

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments
  • GET /v1/instruments/{instrument_id}
  • GET /v1/instruments/search
  • GET /v1/instruments/options/contracts

Executions endpoint

A new endpoint returns individual execution reports for an account. Each execution includes id, order_id, symbol, instrument_id, side, quantity, price, and transaction_time, ordered by transaction time (newest first), with instrument_id, from, to, and pagination filters.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/executions

Omni AI response format changes

Three changes that affect clients parsing Omni AI content:

  • Ticker references inside message text changed from XML-style tags (<ticker>AAPL</ticker>) to markdown links ([AAPL](ticker:AAPL)).
  • Entitlement request fields were renamed: trading_account_ids → account_ids and requested_entitlement_codes → entitlement_codes.
  • The symbolChart chart-card option and its SymbolChart schema were removed; chart cards now use the series-driven dataChart only.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/omni-ai/threads/{thread_id}/messages
  • GET /v1/omni-ai/threads/{thread_id}/response
  • POST /v1/omni-ai/entitlements

Latest Omni messages first

Fetching thread messages now returns the latest page of finalized messages by default (chronological within each page) instead of starting from the earliest message.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/omni-ai/threads/{thread_id}/messages

Fractionable instrument flag

Instruments now include a required is_fractionable boolean indicating whether the instrument supports fractional-quantity orders.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/instruments
  • GET /v1/instruments/{instrument_id}
  • GET /v1/instruments/search
  • GET /v1/instruments/options/contracts

Last-trade size in snapshots

The last_trade object in market-data snapshots gains a required size field — the share quantity of the most recent last-sale-eligible trade.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/market-data/snapshot

Instrument type inferred on order submission

The instrument_type request field is no longer required on order submission — the security type is now inferred from the instrument you reference.

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/accounts/{account_id}/orders

Documented position-instruction lifecycle

The full lifecycle-status model for position instructions is now documented: SENT, ACCEPTED, REJECTED, CANCEL_REQUESTED, CANCELLED, CANCEL_FAILED, and UNKNOWN, along with typical rejection causes (duplicate instruction_id, DNE/CEA on a non-expiry day, insufficient position, unresolved instrument).

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/accounts/{account_id}/positions/instructions
  • GET /v1/accounts/{account_id}/positions/instructions

Batch position instructions and reporting currency

Two additions:

  • Batch submission semantics for position instructions are now defined: all rows accepted returns 200; partial success returns 207 (Multi-Status) with rejected rows carrying a rejection_reason; and all-rejected returns a 4xx/5xx (409 duplicate instruction_id, 400 validation failures, 503 clearing unavailable).
  • A nullable reporting_currency field was added to instrument events, analyst-reporting, and fundamentals responses.

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/accounts/{account_id}/positions/instructions
  • GET /v1/instruments/events
  • GET /v1/instruments/{instrument_id}/analyst-reporting
  • GET /v1/instruments/{instrument_id}/fundamentals

Top-level error removed from position instructions

The separate top-level error field has been removed from the position-instruction response object. Per-row rejection detail is now carried in each row’s rejection_reason.

Affected Endpoints

Section titled “Affected Endpoints”
  • POST /v1/accounts/{account_id}/positions/instructions
  • GET /v1/accounts/{account_id}/positions/instructions

Partial portfolio-history results

Portfolio history can now return a 207 (partial success) when one side of the fetch fails, delivering the available segments alongside a top-level error describing the portion that failed.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/portfolio-history

Bidirectional pagination

page_token now supports paging backward as well as forward: a token can retrieve the next or the previous page of results. This applies to all paginated list endpoints (orders, executions, positions, instruments, events, news, Omni threads and messages, watchlists, and more). No request changes are required.

Affected Endpoints

Section titled “Affected Endpoints”
  • GET /v1/accounts/{account_id}/orders
  • GET /v1/instruments
  • GET /v1/news
  • GET /v1/omni-ai/threads/{thread_id}/messages

Initial release

First release of the Clear Street Trading API — a unified REST API covering order management, positions, market data, and account services.

What’s included

Section titled “What’s included”

  • Accounts — list and fetch accounts, update account settings, and read balances and portfolio history.

  • Orders — submit, list, fetch, replace, and cancel orders. Sides BUY, SELL, and SELL_SHORT; order types MARKET, LIMIT, STOP, and STOP_LIMIT; with support for trailing stops and extended-hours sessions.

  • Positions — list positions, close positions, and manage position instructions.

  • Instruments — look up and search instruments, list option contracts, and read corporate-action events.

  • Instrument data — fundamentals, income statements, balance sheets, cash-flow statements, analyst reporting, and news.

  • Market data — real-time snapshots and daily summaries.

  • Calendar — market clock and market-hours calendar.

  • Watchlists — create and manage watchlists and their items.

  • Omni AI — threads, messages, responses, feedback, and entitlements for Clear Street’s financial AI assistant.

    See Get Started to make your first call.