# V1 ## Domain Types ### Security Type - `Literal["COMMON_STOCK", "PREFERRED_STOCK", "OPTION", 2 more]` Security type - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` # Accounts ## Get Accounts `v1.accounts.get_accounts(AccountGetAccountsParams**kwargs) -> AccountGetAccountsResponse` **get** `/v1/accounts` List accounts the authenticated user has permission to access ### Parameters - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class AccountGetAccountsResponse: …` - `data: AccountList` - `id: int` The unique identifier for the account - `account_holder_entity_id: int` The account holder entity identifier - `full_name: str` The full legal name of the account - `open_date: date` The date the account was opened - `options_level: int` The options level of the account - `short_name: str` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: Optional[date]` The date the account was closed, if applicable ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.accounts.get_accounts() print(response) ``` #### Response ```json { "data": [ { "account_holder_entity_id": 987654321, "close_date": null, "full_name": "Test Trading Account", "id": 19816, "open_date": "2023-01-15", "short_name": "TST-ACCOUNT-01", "status": "ACTIVE", "subtype": "MARGIN", "type": "CUSTOMER" }, { "account_holder_entity_id": 987654322, "close_date": "2024-08-01", "full_name": "Old Test Account", "id": 19817, "open_date": "2021-05-20", "short_name": "TST-ACCOUNT-02-CLOSED", "status": "CLOSED", "subtype": "CASH", "type": "CUSTOMER" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3RfaWQ9MTk4MTc=", "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "total_items": 25, "total_pages": 3 } } ``` ## Get Account By ID `v1.accounts.get_account_by_id(intaccount_id) -> AccountGetAccountByIDResponse` **get** `/v1/accounts/{account_id}` Fetch account details by ID ### Parameters - `account_id: int` ### Returns - `class AccountGetAccountByIDResponse: …` - `data: Account` Represents a trading account - `id: int` The unique identifier for the account - `account_holder_entity_id: int` The account holder entity identifier - `full_name: str` The full legal name of the account - `open_date: date` The date the account was opened - `options_level: int` The options level of the account - `short_name: str` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: Optional[date]` The date the account was closed, if applicable ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.accounts.get_account_by_id( 0, ) print(response) ``` #### Response ```json { "data": { "account_holder_entity_id": 987654321, "close_date": null, "full_name": "Test Trading Account", "id": 19816, "open_date": "2023-01-15", "short_name": "TST-ACCOUNT-01", "status": "ACTIVE", "subtype": "MARGIN", "type": "CUSTOMER" }, "error": null, "metadata": { "request_id": "b7e2d3f4-a1b2-4c3d-8e4f-5a6b7c8d9e0f" } } ``` ## Patch Account By ID `v1.accounts.patch_account_by_id(intaccount_id, AccountPatchAccountByIDParams**kwargs) -> AccountPatchAccountByIDResponse` **patch** `/v1/accounts/{account_id}` Update account risk settings ### Parameters - `account_id: int` - `risk: Optional[RiskSettingsParam]` Risk settings for the account - `max_notional: Optional[str]` The maximum notional value available to the account ### Returns - `class AccountPatchAccountByIDResponse: …` - `data: AccountSettings` - `risk: Optional[RiskSettings]` Risk settings for the account - `max_notional: Optional[str]` The maximum notional value available to the account ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.accounts.patch_account_by_id( account_id=0, ) print(response) ``` #### Response ```json { "data": { "risk": { "max_notional": "5000000.00" } }, "error": null, "metadata": { "request_id": "c8f3e4a5-b2c3-5d4e-9f0a-6b7c8d9e0f1a" } } ``` ## Get Account Balances `v1.accounts.get_account_balances(intaccount_id, AccountGetAccountBalancesParams**kwargs) -> AccountGetAccountBalancesResponse` **get** `/v1/accounts/{account_id}/balances` Fetch account balance information ### Parameters - `account_id: int` - `top_margin_contributors_limit: Optional[int]` Limit the number of top margin contributors returned by the engine. ### Returns - `class AccountGetAccountBalancesResponse: …` - `data: AccountBalances` Represents the balance details for a trading account - `account_id: int` The unique identifier for the account - `buying_power: str` The total buying power available in the account. - `currency: str` Currency identifier for all monetary values. - `daily_realized_pnl: str` Realized profit or loss since start of day. - `daily_total_pnl: str` Total profit or loss since start of day. - `daily_unrealized_pnl: str` Total unrealized profit or loss across all positions relative to prior close. - `equity: str` The total equity in the account. - `long_market_value: str` The total market value of all long positions. - `margin_type: MarginType` The applicable margin model for the account - `"OTHER"` - `"NONE"` - `"PORTFOLIO_MARGIN"` - `"RISK_BASED_HAIRCUT_BROKER_DEALER"` - `"REG_T"` - `"RISK_BASED_HAIRCUT_MARKET_MAKER"` - `"CIRO"` - `"FUTURES_NLV"` - `"FUTURES_TOT_EQ"` - `open_order_adjustment: str` Signed buying-power correction from open orders. - `settled_cash: str` The amount of cash that is settled and available for withdrawal or trading. - `sod: AccountBalancesSod` Start-of-day snapshot balances. - `buying_power: str` Start-of-day buying power. - `equity: str` Start-of-day equity. - `long_market_value: str` Start-of-day long market value. - `short_market_value: str` Start-of-day short market value. - `asof: Optional[date]` Timestamp for the start-of-day values. - `day_trade_buying_power: Optional[str]` Start-of-day day-trade buying power. - `maintenance_margin_excess: Optional[str]` Start-of-day maintenance margin excess. - `maintenance_margin_requirement: Optional[str]` Start-of-day maintenance margin requirement. - `trade_cash: Optional[str]` Start-of-day trade cash. - `trade_cash: str` Trade-date effective cash. - `unsettled_credits: str` Trade-date unsettled cash credits. - `unsettled_debits: str` Trade-date unsettled cash debits. - `withdrawable_cash: str` The amount of cash currently available to withdraw. - `margin_details: Optional[MarginDetails]` Margin-account-only details. - `day_trade_count: int` The number of day trades executed over the 5 most recent trading days. - `initial_margin_excess: str` Initial margin excess for trade-date balances. - `initial_margin_requirement: str` Initial margin requirement for trade-date balances. - `maintenance_margin_excess: str` Maintenance margin excess for trade-date balances. - `maintenance_margin_requirement: str` Maintenance margin requirement for trade-date balances. - `pattern_day_trader: bool` `true` if the account is currently flagged as a PDT, otherwise `false`. - `day_trade_buying_power_usage: Optional[str]` The amount of day-trade buying power used during the current trading day. - `top_contributors: Optional[List[MarginTopContributor]]` Optional top margin contributors, returned only when explicitly requested. - `day_trade_buying_power_usage: str` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: str` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: str` Maintenance margin requirement attributable to this underlying. - `market_value: str` Net market value attributable to this underlying. - `underlying_instrument_id: str` UUID of the underlying security contributing to margin requirement. - `usage: Optional[MarginDetailsUsage]` Current usage totals. - `total: str` The total margin available in the current model. - `used: str` The amount of margin that is currently being utilized. - `multiplier: Optional[str]` Applied multiplier for margin calculations. - `short_market_value: Optional[str]` The total market value of all short positions. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.accounts.get_account_balances( account_id=0, ) print(response) ``` #### Response ```json { "data": { "account_id": 19816, "buying_power": "45000.00", "currency": "USD", "daily_realized_pnl": "700.00", "daily_total_pnl": "1250.00", "daily_unrealized_pnl": "550.00", "equity": "100000.00", "long_market_value": "30000.00", "margin_type": "NONE", "open_order_adjustment": "-5000.00", "settled_cash": "60000.00", "sod": { "asof": "2023-09-27", "buying_power": "45000.00", "equity": "100000.00", "long_market_value": "30000.00" }, "trade_cash": "60000.00", "unsettled_credits": "20000.00", "unsettled_debits": "10000.00", "withdrawable_cash": "55000.00" }, "error": null, "metadata": { "request_id": "b7e2d3f4-a1b2-4c3d-8e4f-5a6b7c8d9e0f" } } ``` ## Get Portfolio History `v1.accounts.get_portfolio_history(intaccount_id, AccountGetPortfolioHistoryParams**kwargs) -> AccountGetPortfolioHistoryResponse` **get** `/v1/accounts/{account_id}/portfolio-history` Retrieves daily portfolio history for the specified account. ### Parameters - `account_id: int` - `start_date: Union[null, null]` Start date for the portfolio history range, in YYYY-MM-DD format. - `end_date: Optional[Union[null, null]]` Defaults to today in America/New_York when omitted. ### Returns - `class AccountGetPortfolioHistoryResponse: …` - `data: PortfolioHistoryResponse` - `segments: List[PortfolioHistorySegment]` - `date: date` The date for this segment - `eod_equity: str` The equity at the end of the trading day. - `realized_pnl: str` Sum of the profit and loss realized from position closing trading activity. - `sod_equity: str` The equity at the start of the trading day. - `unrealized_pnl: str` Sum of the profit and loss from market changes. - `bought_notional: Optional[str]` Amount bought MTM - `day_pnl: Optional[str]` Sum of the profit and loss from intraday trading activities for the trading day. - `net_pnl: Optional[str]` P&L after netting all realized and unrealized P&L, adjustments, dividends, change in accruals, income and expenses - `position_pnl: Optional[str]` P&L attributable to start-of-day (carried) positions from market movement during this trading day. - `sold_notional: Optional[str]` Amount sold MTM ### Example ```python from datetime import date from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.accounts.get_portfolio_history( account_id=0, start_date=date.fromisoformat("2019-12-27"), ) print(response) ``` #### Response ```json { "data": { "segments": [ { "bought_notional": "39800.00", "date": "2026-04-15", "day_pnl": "850.25", "eod_equity": "100850.25", "net_pnl": "850.25", "position_pnl": "-350.25", "realized_pnl": "1200.50", "sod_equity": "100000.00", "sold_notional": "42500.00", "unrealized_pnl": "-350.25" } ] }, "error": null, "metadata": { "request_id": "f076d6f6-10c9-42a0-98c5-18cebc427e80" } } ``` ## Domain Types ### Account - `class Account: …` Represents a trading account - `id: int` The unique identifier for the account - `account_holder_entity_id: int` The account holder entity identifier - `full_name: str` The full legal name of the account - `open_date: date` The date the account was opened - `options_level: int` The options level of the account - `short_name: str` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: Optional[date]` The date the account was closed, if applicable ### Account Balances - `class AccountBalances: …` Represents the balance details for a trading account - `account_id: int` The unique identifier for the account - `buying_power: str` The total buying power available in the account. - `currency: str` Currency identifier for all monetary values. - `daily_realized_pnl: str` Realized profit or loss since start of day. - `daily_total_pnl: str` Total profit or loss since start of day. - `daily_unrealized_pnl: str` Total unrealized profit or loss across all positions relative to prior close. - `equity: str` The total equity in the account. - `long_market_value: str` The total market value of all long positions. - `margin_type: MarginType` The applicable margin model for the account - `"OTHER"` - `"NONE"` - `"PORTFOLIO_MARGIN"` - `"RISK_BASED_HAIRCUT_BROKER_DEALER"` - `"REG_T"` - `"RISK_BASED_HAIRCUT_MARKET_MAKER"` - `"CIRO"` - `"FUTURES_NLV"` - `"FUTURES_TOT_EQ"` - `open_order_adjustment: str` Signed buying-power correction from open orders. - `settled_cash: str` The amount of cash that is settled and available for withdrawal or trading. - `sod: AccountBalancesSod` Start-of-day snapshot balances. - `buying_power: str` Start-of-day buying power. - `equity: str` Start-of-day equity. - `long_market_value: str` Start-of-day long market value. - `short_market_value: str` Start-of-day short market value. - `asof: Optional[date]` Timestamp for the start-of-day values. - `day_trade_buying_power: Optional[str]` Start-of-day day-trade buying power. - `maintenance_margin_excess: Optional[str]` Start-of-day maintenance margin excess. - `maintenance_margin_requirement: Optional[str]` Start-of-day maintenance margin requirement. - `trade_cash: Optional[str]` Start-of-day trade cash. - `trade_cash: str` Trade-date effective cash. - `unsettled_credits: str` Trade-date unsettled cash credits. - `unsettled_debits: str` Trade-date unsettled cash debits. - `withdrawable_cash: str` The amount of cash currently available to withdraw. - `margin_details: Optional[MarginDetails]` Margin-account-only details. - `day_trade_count: int` The number of day trades executed over the 5 most recent trading days. - `initial_margin_excess: str` Initial margin excess for trade-date balances. - `initial_margin_requirement: str` Initial margin requirement for trade-date balances. - `maintenance_margin_excess: str` Maintenance margin excess for trade-date balances. - `maintenance_margin_requirement: str` Maintenance margin requirement for trade-date balances. - `pattern_day_trader: bool` `true` if the account is currently flagged as a PDT, otherwise `false`. - `day_trade_buying_power_usage: Optional[str]` The amount of day-trade buying power used during the current trading day. - `top_contributors: Optional[List[MarginTopContributor]]` Optional top margin contributors, returned only when explicitly requested. - `day_trade_buying_power_usage: str` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: str` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: str` Maintenance margin requirement attributable to this underlying. - `market_value: str` Net market value attributable to this underlying. - `underlying_instrument_id: str` UUID of the underlying security contributing to margin requirement. - `usage: Optional[MarginDetailsUsage]` Current usage totals. - `total: str` The total margin available in the current model. - `used: str` The amount of margin that is currently being utilized. - `multiplier: Optional[str]` Applied multiplier for margin calculations. - `short_market_value: Optional[str]` The total market value of all short positions. ### Account Balances Sod - `class AccountBalancesSod: …` - `buying_power: str` Start-of-day buying power. - `equity: str` Start-of-day equity. - `long_market_value: str` Start-of-day long market value. - `short_market_value: str` Start-of-day short market value. - `asof: Optional[date]` Timestamp for the start-of-day values. - `day_trade_buying_power: Optional[str]` Start-of-day day-trade buying power. - `maintenance_margin_excess: Optional[str]` Start-of-day maintenance margin excess. - `maintenance_margin_requirement: Optional[str]` Start-of-day maintenance margin requirement. - `trade_cash: Optional[str]` Start-of-day trade cash. ### Account List - `List[Account]` - `id: int` The unique identifier for the account - `account_holder_entity_id: int` The account holder entity identifier - `full_name: str` The full legal name of the account - `open_date: date` The date the account was opened - `options_level: int` The options level of the account - `short_name: str` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: Optional[date]` The date the account was closed, if applicable ### Account Settings - `class AccountSettings: …` - `risk: Optional[RiskSettings]` Risk settings for the account - `max_notional: Optional[str]` The maximum notional value available to the account ### Account Status - `Literal["ACTIVE", "INACTIVE", "CLOSED"]` Account status - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` ### Account Subtype - `Literal["CASH", "MARGIN", "OTHER"]` Account subtype classification providing more granular categorization - `"CASH"` - `"MARGIN"` - `"OTHER"` ### Account Type - `Literal["CUSTOMER", "OTHER"]` Account type classification - `"CUSTOMER"` - `"OTHER"` ### Margin Details - `class MarginDetails: …` - `day_trade_count: int` The number of day trades executed over the 5 most recent trading days. - `initial_margin_excess: str` Initial margin excess for trade-date balances. - `initial_margin_requirement: str` Initial margin requirement for trade-date balances. - `maintenance_margin_excess: str` Maintenance margin excess for trade-date balances. - `maintenance_margin_requirement: str` Maintenance margin requirement for trade-date balances. - `pattern_day_trader: bool` `true` if the account is currently flagged as a PDT, otherwise `false`. - `day_trade_buying_power_usage: Optional[str]` The amount of day-trade buying power used during the current trading day. - `top_contributors: Optional[List[MarginTopContributor]]` Optional top margin contributors, returned only when explicitly requested. - `day_trade_buying_power_usage: str` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: str` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: str` Maintenance margin requirement attributable to this underlying. - `market_value: str` Net market value attributable to this underlying. - `underlying_instrument_id: str` UUID of the underlying security contributing to margin requirement. - `usage: Optional[MarginDetailsUsage]` Current usage totals. - `total: str` The total margin available in the current model. - `used: str` The amount of margin that is currently being utilized. ### Margin Details Usage - `class MarginDetailsUsage: …` - `total: str` The total margin available in the current model. - `used: str` The amount of margin that is currently being utilized. ### Margin Top Contributor - `class MarginTopContributor: …` - `day_trade_buying_power_usage: str` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: str` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: str` Maintenance margin requirement attributable to this underlying. - `market_value: str` Net market value attributable to this underlying. - `underlying_instrument_id: str` UUID of the underlying security contributing to margin requirement. ### Margin Type - `Literal["OTHER", "NONE", "PORTFOLIO_MARGIN", 6 more]` An account's margin type - `"OTHER"` - `"NONE"` - `"PORTFOLIO_MARGIN"` - `"RISK_BASED_HAIRCUT_BROKER_DEALER"` - `"REG_T"` - `"RISK_BASED_HAIRCUT_MARKET_MAKER"` - `"CIRO"` - `"FUTURES_NLV"` - `"FUTURES_TOT_EQ"` ### Portfolio History Response - `class PortfolioHistoryResponse: …` - `segments: List[PortfolioHistorySegment]` - `date: date` The date for this segment - `eod_equity: str` The equity at the end of the trading day. - `realized_pnl: str` Sum of the profit and loss realized from position closing trading activity. - `sod_equity: str` The equity at the start of the trading day. - `unrealized_pnl: str` Sum of the profit and loss from market changes. - `bought_notional: Optional[str]` Amount bought MTM - `day_pnl: Optional[str]` Sum of the profit and loss from intraday trading activities for the trading day. - `net_pnl: Optional[str]` P&L after netting all realized and unrealized P&L, adjustments, dividends, change in accruals, income and expenses - `position_pnl: Optional[str]` P&L attributable to start-of-day (carried) positions from market movement during this trading day. - `sold_notional: Optional[str]` Amount sold MTM ### Portfolio History Segment - `class PortfolioHistorySegment: …` - `date: date` The date for this segment - `eod_equity: str` The equity at the end of the trading day. - `realized_pnl: str` Sum of the profit and loss realized from position closing trading activity. - `sod_equity: str` The equity at the start of the trading day. - `unrealized_pnl: str` Sum of the profit and loss from market changes. - `bought_notional: Optional[str]` Amount bought MTM - `day_pnl: Optional[str]` Sum of the profit and loss from intraday trading activities for the trading day. - `net_pnl: Optional[str]` P&L after netting all realized and unrealized P&L, adjustments, dividends, change in accruals, income and expenses - `position_pnl: Optional[str]` P&L attributable to start-of-day (carried) positions from market movement during this trading day. - `sold_notional: Optional[str]` Amount sold MTM ### Risk Settings - `class RiskSettings: …` Risk settings for an account - `max_notional: Optional[str]` The maximum notional value available to the account ### Account Get Accounts Response - `class AccountGetAccountsResponse: …` - `data: AccountList` - `id: int` The unique identifier for the account - `account_holder_entity_id: int` The account holder entity identifier - `full_name: str` The full legal name of the account - `open_date: date` The date the account was opened - `options_level: int` The options level of the account - `short_name: str` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: Optional[date]` The date the account was closed, if applicable ### Account Get Account By ID Response - `class AccountGetAccountByIDResponse: …` - `data: Account` Represents a trading account - `id: int` The unique identifier for the account - `account_holder_entity_id: int` The account holder entity identifier - `full_name: str` The full legal name of the account - `open_date: date` The date the account was opened - `options_level: int` The options level of the account - `short_name: str` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: Optional[date]` The date the account was closed, if applicable ### Account Patch Account By ID Response - `class AccountPatchAccountByIDResponse: …` - `data: AccountSettings` - `risk: Optional[RiskSettings]` Risk settings for the account - `max_notional: Optional[str]` The maximum notional value available to the account ### Account Get Account Balances Response - `class AccountGetAccountBalancesResponse: …` - `data: AccountBalances` Represents the balance details for a trading account - `account_id: int` The unique identifier for the account - `buying_power: str` The total buying power available in the account. - `currency: str` Currency identifier for all monetary values. - `daily_realized_pnl: str` Realized profit or loss since start of day. - `daily_total_pnl: str` Total profit or loss since start of day. - `daily_unrealized_pnl: str` Total unrealized profit or loss across all positions relative to prior close. - `equity: str` The total equity in the account. - `long_market_value: str` The total market value of all long positions. - `margin_type: MarginType` The applicable margin model for the account - `"OTHER"` - `"NONE"` - `"PORTFOLIO_MARGIN"` - `"RISK_BASED_HAIRCUT_BROKER_DEALER"` - `"REG_T"` - `"RISK_BASED_HAIRCUT_MARKET_MAKER"` - `"CIRO"` - `"FUTURES_NLV"` - `"FUTURES_TOT_EQ"` - `open_order_adjustment: str` Signed buying-power correction from open orders. - `settled_cash: str` The amount of cash that is settled and available for withdrawal or trading. - `sod: AccountBalancesSod` Start-of-day snapshot balances. - `buying_power: str` Start-of-day buying power. - `equity: str` Start-of-day equity. - `long_market_value: str` Start-of-day long market value. - `short_market_value: str` Start-of-day short market value. - `asof: Optional[date]` Timestamp for the start-of-day values. - `day_trade_buying_power: Optional[str]` Start-of-day day-trade buying power. - `maintenance_margin_excess: Optional[str]` Start-of-day maintenance margin excess. - `maintenance_margin_requirement: Optional[str]` Start-of-day maintenance margin requirement. - `trade_cash: Optional[str]` Start-of-day trade cash. - `trade_cash: str` Trade-date effective cash. - `unsettled_credits: str` Trade-date unsettled cash credits. - `unsettled_debits: str` Trade-date unsettled cash debits. - `withdrawable_cash: str` The amount of cash currently available to withdraw. - `margin_details: Optional[MarginDetails]` Margin-account-only details. - `day_trade_count: int` The number of day trades executed over the 5 most recent trading days. - `initial_margin_excess: str` Initial margin excess for trade-date balances. - `initial_margin_requirement: str` Initial margin requirement for trade-date balances. - `maintenance_margin_excess: str` Maintenance margin excess for trade-date balances. - `maintenance_margin_requirement: str` Maintenance margin requirement for trade-date balances. - `pattern_day_trader: bool` `true` if the account is currently flagged as a PDT, otherwise `false`. - `day_trade_buying_power_usage: Optional[str]` The amount of day-trade buying power used during the current trading day. - `top_contributors: Optional[List[MarginTopContributor]]` Optional top margin contributors, returned only when explicitly requested. - `day_trade_buying_power_usage: str` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: str` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: str` Maintenance margin requirement attributable to this underlying. - `market_value: str` Net market value attributable to this underlying. - `underlying_instrument_id: str` UUID of the underlying security contributing to margin requirement. - `usage: Optional[MarginDetailsUsage]` Current usage totals. - `total: str` The total margin available in the current model. - `used: str` The amount of margin that is currently being utilized. - `multiplier: Optional[str]` Applied multiplier for margin calculations. - `short_market_value: Optional[str]` The total market value of all short positions. ### Account Get Portfolio History Response - `class AccountGetPortfolioHistoryResponse: …` - `data: PortfolioHistoryResponse` - `segments: List[PortfolioHistorySegment]` - `date: date` The date for this segment - `eod_equity: str` The equity at the end of the trading day. - `realized_pnl: str` Sum of the profit and loss realized from position closing trading activity. - `sod_equity: str` The equity at the start of the trading day. - `unrealized_pnl: str` Sum of the profit and loss from market changes. - `bought_notional: Optional[str]` Amount bought MTM - `day_pnl: Optional[str]` Sum of the profit and loss from intraday trading activities for the trading day. - `net_pnl: Optional[str]` P&L after netting all realized and unrealized P&L, adjustments, dividends, change in accruals, income and expenses - `position_pnl: Optional[str]` P&L attributable to start-of-day (carried) positions from market movement during this trading day. - `sold_notional: Optional[str]` Amount sold MTM # API Version ## Get the API version. `v1.api_version.get_version() -> APIVersionGetVersionResponse` **get** `/v1/version` Returns the current version string for this API endpoint. ### Returns - `class APIVersionGetVersionResponse: …` - `data: Version` API version information - `version: str` API version string ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.api_version.get_version() print(response) ``` #### Response ```json { "data": { "version": "2025-10-31" }, "error": null, "metadata": { "request_id": "2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f" } } ``` ## Domain Types ### Version - `class Version: …` API version information - `version: str` API version string ### API Version Get Version Response - `class APIVersionGetVersionResponse: …` - `data: Version` API version information - `version: str` API version string # Calendar ## Get Clock `v1.calendar.get_clock() -> CalendarGetClockResponse` **get** `/v1/clock` Returns the current server time in UTC. ### Returns - `class CalendarGetClockResponse: …` - `data: ClockDetail` Current server time and market clock information - `clock: datetime` Current server time in UTC ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.calendar.get_clock() print(response) ``` #### Response ```json { "data": { "clock": "2025-03-01T03:35:00.000000000Z" }, "error": null, "metadata": { "request_id": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e" } } ``` ## Get Market Hours Calendar. `v1.calendar.get_market_hours_calendar(CalendarGetMarketHoursCalendarParams**kwargs) -> CalendarGetMarketHoursCalendarResponse` **get** `/v1/calendars/market-hours` Retrieves comprehensive trading hours including pre-market, regular, and after-hours sessions. Returns market status, session times, and next session schedules. ### Parameters - `date: str` The date to query market hours for (YYYY-MM-DD). Defaults to today. - `market: Optional[MarketType]` Market type to query (us_equities, us_options). If omitted, returns all markets. - `"us_equities"` - `"us_options"` ### Returns - `class CalendarGetMarketHoursCalendarResponse: …` - `data: MarketHoursDetailList` - `current_time: datetime` Current time in market timezone with offset - `date: date` The date for which market hours are provided - `market: MarketType` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: str` Human-readable market name - `next_sessions: TradingSessions` Next trading day's session schedules (without time_until fields) - `after_hours: Optional[SessionSchedule]` After-hours session schedule, null if not available - `close: datetime` Session close timestamp with timezone offset - `open: datetime` Session open timestamp with timezone offset - `time_until_close: Optional[str]` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: Optional[str]` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: Optional[SessionSchedule]` Pre-market session schedule, null if not available - `regular: Optional[SessionSchedule]` Regular trading session schedule, null if holiday/weekend - `status: MarketStatus` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: bool` Whether the market is currently open (real-time) - `current_session: Optional[MarketSessionType]` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` - `timezone: str` IANA timezone identifier for the market - `today_sessions: TradingSessions` Trading session schedules for the requested date with time_until fields ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.calendar.get_market_hours_calendar( date="date", ) print(response) ``` #### Response ```json { "data": [ { "current_time": "2025-11-28T11:00:00-05:00", "date": "2025-11-28", "market": "us_equities", "market_name": "US Equities", "next_sessions": { "after_hours": { "close": "2025-12-01T20:00:00-05:00", "open": "2025-12-01T16:00:00-05:00" }, "pre_market": { "close": "2025-12-01T09:30:00-05:00", "open": "2025-12-01T04:00:00-05:00" }, "regular": { "close": "2025-12-01T16:00:00-05:00", "open": "2025-12-01T09:30:00-05:00" } }, "status": { "current_session": "regular", "day_type": "EARLY_CLOSE", "is_open": true }, "timezone": "America/New_York", "today_sessions": { "pre_market": { "close": "2025-11-28T09:30:00-05:00", "open": "2025-11-28T04:00:00-05:00" }, "regular": { "close": "2025-11-28T13:00:00-05:00", "open": "2025-11-28T09:30:00-05:00", "time_until_close": "PT2H" } } } ], "error": null, "metadata": { "request_id": "3d4e5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f8a" } } ``` ## Domain Types ### Clock Detail - `class ClockDetail: …` Current server time and market clock information - `clock: datetime` Current server time in UTC ### Day Type - `Literal["TRADING_DAY", "EARLY_CLOSE", "HOLIDAY", "WEEKEND"]` Day type for market hours - indicates the type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` ### Market Hours Detail - `class MarketHoursDetail: …` Comprehensive market hours information for a specific market and date - `current_time: datetime` Current time in market timezone with offset - `date: date` The date for which market hours are provided - `market: MarketType` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: str` Human-readable market name - `next_sessions: TradingSessions` Next trading day's session schedules (without time_until fields) - `after_hours: Optional[SessionSchedule]` After-hours session schedule, null if not available - `close: datetime` Session close timestamp with timezone offset - `open: datetime` Session open timestamp with timezone offset - `time_until_close: Optional[str]` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: Optional[str]` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: Optional[SessionSchedule]` Pre-market session schedule, null if not available - `regular: Optional[SessionSchedule]` Regular trading session schedule, null if holiday/weekend - `status: MarketStatus` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: bool` Whether the market is currently open (real-time) - `current_session: Optional[MarketSessionType]` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` - `timezone: str` IANA timezone identifier for the market - `today_sessions: TradingSessions` Trading session schedules for the requested date with time_until fields ### Market Hours Detail List - `List[MarketHoursDetail]` - `current_time: datetime` Current time in market timezone with offset - `date: date` The date for which market hours are provided - `market: MarketType` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: str` Human-readable market name - `next_sessions: TradingSessions` Next trading day's session schedules (without time_until fields) - `after_hours: Optional[SessionSchedule]` After-hours session schedule, null if not available - `close: datetime` Session close timestamp with timezone offset - `open: datetime` Session open timestamp with timezone offset - `time_until_close: Optional[str]` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: Optional[str]` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: Optional[SessionSchedule]` Pre-market session schedule, null if not available - `regular: Optional[SessionSchedule]` Regular trading session schedule, null if holiday/weekend - `status: MarketStatus` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: bool` Whether the market is currently open (real-time) - `current_session: Optional[MarketSessionType]` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` - `timezone: str` IANA timezone identifier for the market - `today_sessions: TradingSessions` Trading session schedules for the requested date with time_until fields ### Market Session Type - `Literal["pre_market", "regular", "after_hours"]` Session type for market hours - `"pre_market"` - `"regular"` - `"after_hours"` ### Market Status - `class MarketStatus: …` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: bool` Whether the market is currently open (real-time) - `current_session: Optional[MarketSessionType]` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` ### Market Type - `Literal["us_equities", "us_options"]` Market type for market hours calendar endpoint - `"us_equities"` - `"us_options"` ### Session Schedule - `class SessionSchedule: …` Session schedule with open and close timestamps - `close: datetime` Session close timestamp with timezone offset - `open: datetime` Session open timestamp with timezone offset - `time_until_close: Optional[str]` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: Optional[str]` ISO 8601 duration until session opens. Null if session has already started or closed. ### Trading Sessions - `class TradingSessions: …` Trading sessions for a market day with full timestamps - `after_hours: Optional[SessionSchedule]` After-hours session schedule, null if not available - `close: datetime` Session close timestamp with timezone offset - `open: datetime` Session open timestamp with timezone offset - `time_until_close: Optional[str]` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: Optional[str]` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: Optional[SessionSchedule]` Pre-market session schedule, null if not available - `regular: Optional[SessionSchedule]` Regular trading session schedule, null if holiday/weekend ### Calendar Get Clock Response - `class CalendarGetClockResponse: …` - `data: ClockDetail` Current server time and market clock information - `clock: datetime` Current server time in UTC ### Calendar Get Market Hours Calendar Response - `class CalendarGetMarketHoursCalendarResponse: …` - `data: MarketHoursDetailList` - `current_time: datetime` Current time in market timezone with offset - `date: date` The date for which market hours are provided - `market: MarketType` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: str` Human-readable market name - `next_sessions: TradingSessions` Next trading day's session schedules (without time_until fields) - `after_hours: Optional[SessionSchedule]` After-hours session schedule, null if not available - `close: datetime` Session close timestamp with timezone offset - `open: datetime` Session open timestamp with timezone offset - `time_until_close: Optional[str]` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: Optional[str]` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: Optional[SessionSchedule]` Pre-market session schedule, null if not available - `regular: Optional[SessionSchedule]` Regular trading session schedule, null if holiday/weekend - `status: MarketStatus` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: bool` Whether the market is currently open (real-time) - `current_session: Optional[MarketSessionType]` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` - `timezone: str` IANA timezone identifier for the market - `today_sessions: TradingSessions` Trading session schedules for the requested date with time_until fields # Instrument Data ## Get All Instrument Events `v1.instrument_data.get_all_instrument_events(InstrumentDataGetAllInstrumentEventsParams**kwargs) -> InstrumentDataGetAllInstrumentEventsResponse` **get** `/v1/instruments/events` List instrument events across all securities. Retrieves all instrument events grouped by date. ### Parameters - `event_types: Optional[List[AllEventsEventType]]` Filter by event type(s). Comma-delimited list. Example: `event_types=EARNINGS,IPO`. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `from_date: Optional[str]` The start date for the query range, inclusive (YYYY-MM-DD). - `instrument_ids: Optional[Sequence[str]]` Filter by OEMS instrument ID(s). Comma-delimited list of UUIDs. Example: `instrument_ids=550e8400-e29b-41d4-a716-446655440000`. - `to_date: Optional[str]` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `class InstrumentDataGetAllInstrumentEventsResponse: …` - `data: InstrumentAllEventsData` All-events payload grouped by date. - `event_dates: List[InstrumentEventsByDate]` Events grouped by date in descending order. - `date: date` Event date. - `events: List[InstrumentEventEnvelope]` Flat event envelopes for this date. - `symbol: str` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: Optional[InstrumentDividendEvent]` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: str` The adjusted dividend amount accounting for any splits. - `ex_date: date` The day the stock starts trading without the right to receive that dividend. - `declaration_date: Optional[date]` The declaration date of the dividend - `dividend_amount: Optional[str]` The dividend amount per share. - `dividend_yield: Optional[str]` The dividend yield as a percentage of the stock price. - `frequency: Optional[str]` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: Optional[date]` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: Optional[date]` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: Optional[InstrumentEarnings]` Earnings payload when type is EARNINGS. - `date: date` The date when the earnings report was published - `eps_actual: Optional[str]` The actual earnings per share (EPS) for the period - `eps_estimate: Optional[str]` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: Optional[str]` The percentage difference between actual and estimated EPS - `revenue_actual: Optional[str]` The actual total revenue for the period - `revenue_estimate: Optional[str]` The estimated total revenue for the period - `revenue_surprise_percent: Optional[str]` The percentage difference between actual and estimated revenue - `instrument_id: Optional[str]` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: Optional[InstrumentEventIpoItem]` IPO payload when type is IPO. - `actions: Optional[str]` IPO action. - `announced_at: Optional[datetime]` IPO announced timestamp. - `company: Optional[str]` IPO company name. - `exchange: Optional[str]` IPO exchange. - `market_cap: Optional[str]` IPO market cap. - `price_range: Optional[str]` IPO price range. - `shares: Optional[str]` IPO shares offered. - `name: Optional[str]` Instrument name associated with the event, when available. - `reporting_currency: Optional[str]` The currency used for reporting financial data. - `stock_split_event_data: Optional[InstrumentSplitEvent]` Stock split payload when type is STOCK_SPLIT. - `date: date` The date of the stock split - `denominator: str` The denominator of the split ratio - `numerator: str` The numerator of the split ratio - `split_type: str` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.get_all_instrument_events() print(response) ``` #### Response ```json { "data": { "event_dates": [ { "date": "2026-04-23", "events": [ { "dividend_event_data": { "adjusted_dividend_amount": "0.5236", "declaration_date": "2026-04-22", "dividend_amount": "0.5236", "dividend_yield": "43.82881469863321", "ex_date": "2026-04-23", "frequency": "Weekly", "payment_date": "2026-04-24", "record_date": "2026-04-23" }, "instrument_id": "2281b543-7136-4008-aa0a-a402bf9d9f90", "name": "YieldMax ABNB Option Income Strategy ETF", "reporting_currency": "USD", "symbol": "ABNY", "type": "DIVIDEND" }, { "dividend_event_data": { "adjusted_dividend_amount": "0.1432", "declaration_date": "2026-04-22", "dividend_amount": "0.1432", "dividend_yield": "181.7918287937743", "ex_date": "2026-04-23", "frequency": "Weekly", "payment_date": "2026-04-24", "record_date": "2026-04-23" }, "instrument_id": "4b33fa52-8ab6-43f5-a8df-042e0c63d20e", "name": "YieldMax AI Option Income Strategy ETF", "reporting_currency": "USD", "symbol": "AIYY", "type": "DIVIDEND" } ] } ] }, "metadata": { "request_id": "5efbf08a-9067-4491-9f29-cf0b233507ef" } } ``` ## Get Instrument Events `v1.instrument_data.get_instrument_events(InstrumentIDOrSymbolinstrument_id, InstrumentDataGetInstrumentEventsParams**kwargs) -> InstrumentDataGetInstrumentEventsResponse` **get** `/v1/instruments/{instrument_id}/events` Retrieves corporate events (dividends, splits, etc.) for an instrument, grouped by event type. Date range defaults: - `from_date`: today - 365 days - `to_date`: today + 60 days ### Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID - `from_date: Optional[str]` The start date for the query range, inclusive (YYYY-MM-DD). - `to_date: Optional[str]` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `class InstrumentDataGetInstrumentEventsResponse: …` - `data: InstrumentEventsData` Grouped instrument events by type - `dividends: List[InstrumentDividendEvent]` Dividend distribution events - `adjusted_dividend_amount: str` The adjusted dividend amount accounting for any splits. - `ex_date: date` The day the stock starts trading without the right to receive that dividend. - `declaration_date: Optional[date]` The declaration date of the dividend - `dividend_amount: Optional[str]` The dividend amount per share. - `dividend_yield: Optional[str]` The dividend yield as a percentage of the stock price. - `frequency: Optional[str]` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: Optional[date]` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: Optional[date]` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings: List[InstrumentEarnings]` Earnings announcement events - `date: date` The date when the earnings report was published - `eps_actual: Optional[str]` The actual earnings per share (EPS) for the period - `eps_estimate: Optional[str]` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: Optional[str]` The percentage difference between actual and estimated EPS - `revenue_actual: Optional[str]` The actual total revenue for the period - `revenue_estimate: Optional[str]` The estimated total revenue for the period - `revenue_surprise_percent: Optional[str]` The percentage difference between actual and estimated revenue - `instrument_id: str` OEMS instrument UUID from the request - `splits: List[InstrumentSplitEvent]` Stock split events - `date: date` The date of the stock split - `denominator: str` The denominator of the split ratio - `numerator: str` The numerator of the split ratio - `split_type: str` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") - `reporting_currency: Optional[str]` The currency used for reporting financial data ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.get_instrument_events( instrument_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response) ``` #### Response ```json { "data": { "dividends": [ { "adjusted_dividend_amount": "0.25", "declaration_date": "2024-10-31", "dividend_amount": "0.25", "dividend_yield": "0.44", "ex_date": "2024-11-08", "frequency": "Quarterly", "payment_date": "2024-11-14", "record_date": "2024-11-11" } ], "earnings": [ { "date": "2024-10-31", "eps_actual": "1.64", "eps_estimate": "1.60", "eps_surprise_percent": "2.5", "revenue_actual": "94930000000", "revenue_estimate": "94500000000", "revenue_surprise_percent": "0.45" } ], "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "reporting_currency": "USD", "splits": [ { "date": "2020-08-31", "denominator": "1", "numerator": "4", "split_type": "stock-split" } ] }, "error": null, "metadata": { "request_id": "0f1a2b3c-4d5e-6789-8a7b-6c5d4e3f2a1b" } } ``` ## Get Instrument Fundamentals `v1.instrument_data.get_instrument_fundamentals(InstrumentIDOrSymbolinstrument_id) -> InstrumentDataGetInstrumentFundamentalsResponse` **get** `/v1/instruments/{instrument_id}/fundamentals` Retrieves supplemental fundamentals and company profile data for an instrument. ### Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Returns - `class InstrumentDataGetInstrumentFundamentalsResponse: …` - `data: InstrumentFundamentals` Supplemental fundamentals and company profile data for an instrument. - `average_volume: Optional[int]` The average daily trading volume over the past 30 days - `beta: Optional[str]` The beta value, measuring the instrument's volatility relative to the overall market - `description: Optional[str]` A detailed description of the instrument or company - `dividend_yield: Optional[str]` The trailing twelve months (TTM) dividend yield - `earnings_per_share: Optional[str]` The trailing twelve months (TTM) earnings per share - `fifty_two_week_high: Optional[str]` The highest price over the last 52 weeks - `fifty_two_week_low: Optional[str]` The lowest price over the last 52 weeks - `industry: Optional[str]` The specific industry of the instrument's issuer - `list_date: Optional[date]` The date the instrument was first listed - `logo_url: Optional[str]` URL to a representative logo image for the instrument or issuer - `market_cap: Optional[str]` The total market capitalization - `previous_close: Optional[str]` The closing price from the previous trading day - `price_to_earnings: Optional[str]` The price-to-earnings (P/E) ratio for the trailing twelve months (TTM) - `reporting_currency: Optional[str]` The currency used for reporting financial data - `sector: Optional[str]` The business sector of the instrument's issuer ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.get_instrument_fundamentals( "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response) ``` #### Response ```json { "data": { "average_volume": 76000000, "beta": "1.20", "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.", "dividend_yield": "0.005", "earnings_per_share": "5.61", "fifty_two_week_high": "230.00", "fifty_two_week_low": "165.00", "industry": "Consumer Electronics", "list_date": "1980-12-12", "logo_url": "https://example.com/logos/aapl.png", "market_cap": "2800000000000", "previous_close": "210.87", "price_to_earnings": "30.5", "reporting_currency": "USD", "sector": "Technology" }, "error": null, "metadata": { "request_id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" } } ``` ## Get Instrument Balance Sheet Statements `v1.instrument_data.get_instrument_balance_sheet_statements(InstrumentIDOrSymbolinstrument_id, InstrumentDataGetInstrumentBalanceSheetStatementsParams**kwargs) -> InstrumentDataGetInstrumentBalanceSheetStatementsResponse` **get** `/v1/instruments/{instrument_id}/balance-sheets` Get balance sheet statements for an instrument. Retrieves quarterly balance sheet statements for a specific instrument, sorted by fiscal period (most recent first). Date range defaults: - `from_date`: None (no lower bound) - `to_date`: None (no upper bound) ### Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID - `from_date: Optional[str]` The start date for the query range, inclusive (YYYY-MM-DD). - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `to_date: Optional[str]` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `class InstrumentDataGetInstrumentBalanceSheetStatementsResponse: …` - `data: InstrumentBalanceSheetStatementList` - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `account_payables: Optional[str]` Account payables - `accounts_receivables: Optional[str]` Accounts receivables - `accrued_expenses: Optional[str]` Accrued expenses - `accumulated_other_comprehensive_income_loss: Optional[str]` Accumulated other comprehensive income/loss - `additional_paid_in_capital: Optional[str]` Additional paid-in capital - `capital_lease_obligations: Optional[str]` Capital lease obligations (total) - `capital_lease_obligations_current: Optional[str]` Capital lease obligations (current portion) - `cash_and_cash_equivalents: Optional[str]` Cash and cash equivalents - `cash_and_short_term_investments: Optional[str]` Cash and short-term investments combined - `common_stock: Optional[str]` Common stock - `deferred_revenue: Optional[str]` Deferred revenue - `deferred_revenue_non_current: Optional[str]` Deferred revenue (non-current) - `deferred_tax_liabilities_non_current: Optional[str]` Deferred tax liabilities (non-current) - `goodwill: Optional[str]` Goodwill - `goodwill_and_intangible_assets: Optional[str]` Goodwill and intangible assets combined - `intangible_assets: Optional[str]` Intangible assets - `inventory: Optional[str]` Inventory - `long_term_debt: Optional[str]` Long-term debt - `long_term_investments: Optional[str]` Long-term investments - `minority_interest: Optional[str]` Minority interest - `net_debt: Optional[str]` Net debt (total debt minus cash) - `net_receivables: Optional[str]` Net receivables - `other_assets: Optional[str]` Other assets - `other_current_assets: Optional[str]` Other current assets - `other_current_liabilities: Optional[str]` Other current liabilities - `other_liabilities: Optional[str]` Other liabilities - `other_non_current_assets: Optional[str]` Other non-current assets - `other_non_current_liabilities: Optional[str]` Other non-current liabilities - `other_payables: Optional[str]` Other payables - `other_receivables: Optional[str]` Other receivables - `other_total_stockholders_equity: Optional[str]` Other total stockholders equity - `preferred_stock: Optional[str]` Preferred stock - `prepaids: Optional[str]` Prepaids - `property_plant_and_equipment_net: Optional[str]` Property, plant and equipment net of depreciation - `retained_earnings: Optional[str]` Retained earnings - `short_term_debt: Optional[str]` Short-term debt - `short_term_investments: Optional[str]` Short-term investments - `tax_assets: Optional[str]` Tax assets - `tax_payables: Optional[str]` Tax payables - `total_assets: Optional[str]` Total assets - `total_current_assets: Optional[str]` Total current assets - `total_current_liabilities: Optional[str]` Total current liabilities - `total_debt: Optional[str]` Total debt - `total_equity: Optional[str]` Total equity - `total_investments: Optional[str]` Total investments - `total_liabilities: Optional[str]` Total liabilities - `total_liabilities_and_total_equity: Optional[str]` Total liabilities and total equity - `total_non_current_assets: Optional[str]` Total non-current assets - `total_non_current_liabilities: Optional[str]` Total non-current liabilities - `total_payables: Optional[str]` Total payables - `total_stockholders_equity: Optional[str]` Total stockholders equity - `treasury_stock: Optional[str]` Treasury stock ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.get_instrument_balance_sheet_statements( instrument_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response) ``` #### Response ```json { "data": [ { "accepted_date": "2025-05-02T14:30:00Z", "cash_and_cash_equivalents": "29943000000", "filing_date": "2025-05-01", "net_debt": "76323000000", "period": "Q1", "period_type": "QUARTERLY", "reported_currency": "USD", "total_assets": "352583000000", "total_debt": "106266000000", "total_liabilities": "308258000000", "total_stockholders_equity": "56727000000", "year": 2025 } ], "error": null, "metadata": { "next_page_token": "AAAAAAAAAGQAAAAAAAAAZQ==", "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "total_items": 20, "total_pages": 2 } } ``` ## Get Instrument Income Statements `v1.instrument_data.get_instrument_income_statements(InstrumentIDOrSymbolinstrument_id, InstrumentDataGetInstrumentIncomeStatementsParams**kwargs) -> InstrumentDataGetInstrumentIncomeStatementsResponse` **get** `/v1/instruments/{instrument_id}/income-statements` Retrieves quarterly income statements for a specific instrument, sorted by fiscal period (most recent first). Date range defaults: - `from_date`: None (no lower bound) - `to_date`: None (no upper bound) ### Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID - `from_date: Optional[str]` The start date for the query range, inclusive (YYYY-MM-DD). - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `to_date: Optional[str]` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `class InstrumentDataGetInstrumentIncomeStatementsResponse: …` - `data: InstrumentIncomeStatementList` - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `bottom_line_net_income: Optional[str]` Bottom line net income after all adjustments - `cost_and_expenses: Optional[str]` Total costs and expenses - `cost_of_revenue: Optional[str]` Direct costs attributable to producing goods sold - `depreciation_and_amortization: Optional[str]` Depreciation and amortization expenses - `ebit: Optional[str]` Earnings before interest and taxes - `ebitda: Optional[str]` Earnings before interest, taxes, depreciation, and amortization - `eps: Optional[str]` Basic earnings per share - `eps_diluted: Optional[str]` Diluted earnings per share - `general_and_administrative_expenses: Optional[str]` General administrative overhead expenses - `gross_profit: Optional[str]` Revenue minus cost of revenue - `income_before_tax: Optional[str]` Income before income tax expense - `income_tax_expense: Optional[str]` Income tax expense for the period - `interest_expense: Optional[str]` Interest paid on debt - `interest_income: Optional[str]` Interest earned on investments and cash - `net_income: Optional[str]` Total net income for the period - `net_income_deductions: Optional[str]` Deductions from net income - `net_income_from_continuing_operations: Optional[str]` Net income from continuing operations - `net_income_from_discontinued_operations: Optional[str]` Net income from discontinued operations - `net_interest_income: Optional[str]` Net interest income (interest income minus interest expense) - `non_operating_income_excluding_interest: Optional[str]` Non-operating income excluding interest - `operating_expenses: Optional[str]` Total operating expenses - `operating_income: Optional[str]` Income from core business operations - `other_adjustments_to_net_income: Optional[str]` Other adjustments to net income - `other_expenses: Optional[str]` Other miscellaneous expenses - `research_and_development_expenses: Optional[str]` Expenditure on research and development activities - `revenue: Optional[str]` Total revenue from sales of goods and services - `selling_and_marketing_expenses: Optional[str]` Expenditure on marketing and sales activities - `selling_general_and_administrative_expenses: Optional[str]` Combined selling, general, and administrative expenses - `total_other_income_expenses_net: Optional[str]` Net of other income and expenses - `weighted_average_shs_out: Optional[str]` Weighted average shares outstanding (basic) - `weighted_average_shs_out_dil: Optional[str]` Weighted average shares outstanding (diluted) ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.get_instrument_income_statements( instrument_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response) ``` #### Response ```json { "data": [ { "accepted_date": "2025-05-02T14:30:00Z", "cost_of_revenue": "52080000000", "eps": "1.40", "eps_diluted": "1.38", "filing_date": "2025-05-01", "gross_profit": "42850000000", "net_income": "22200000000", "operating_income": "26550000000", "period": "Q1", "period_type": "QUARTERLY", "reported_currency": "USD", "revenue": "94930000000", "year": 2025 } ], "error": null, "metadata": { "next_page_token": "AAAAAAAAAGQAAAAAAAAAZQ==", "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "total_items": 20, "total_pages": 2 } } ``` ## Get Instrument Analyst Consensus `v1.instrument_data.get_instrument_analyst_consensus(InstrumentIDOrSymbolinstrument_id, InstrumentDataGetInstrumentAnalystConsensusParams**kwargs) -> InstrumentDataGetInstrumentAnalystConsensusResponse` **get** `/v1/instruments/{instrument_id}/analyst-reporting` Retrieves analyst ratings and price targets for an instrument. ### Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID - `from_: Optional[Union[null, null]]` The start date for the query range, inclusive (YYYY-MM-DD) - `to: Optional[Union[null, null]]` The end date for the query range, inclusive (YYYY-MM-DD) ### Returns - `class InstrumentDataGetInstrumentAnalystConsensusResponse: …` - `data: InstrumentAnalystConsensus` Aggregated analyst consensus metrics - `date: date` The date the consensus snapshot was generated - `distribution: Optional[AnalystDistribution]` Count of individual analyst recommendations by category - `buy: int` Number of buy recommendations - `hold: int` Number of hold recommendations - `sell: int` Number of sell recommendations - `strong_buy: int` Number of strong buy recommendations - `strong_sell: int` Number of strong sell recommendations - `price_target: Optional[PriceTarget]` Aggregated analyst price target statistics - `average: str` Average analyst price target - `currency: str` ISO 4217 currency code of the price targets - `high: str` Highest analyst price target - `low: str` Lowest analyst price target - `rating: Optional[AnalystRating]` Consensus analyst rating - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.get_instrument_analyst_consensus( instrument_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response) ``` #### Response ```json { "data": { "date": "2025-10-01", "distribution": { "buy": 20, "hold": 3, "sell": 1, "strong_buy": 18, "strong_sell": 0 }, "price_target": { "average": "240.00", "currency": "USD", "high": "275.00", "low": "190.00" }, "rating": "BUY" }, "error": null, "metadata": { "request_id": "9e0f1a2b-3c4d-5e6f-7890-1a2b3c4d5e6f" } } ``` ## Get Instrument Cash Flow Statements `v1.instrument_data.get_instrument_cash_flow_statements(InstrumentIDOrSymbolinstrument_id, InstrumentDataGetInstrumentCashFlowStatementsParams**kwargs) -> InstrumentDataGetInstrumentCashFlowStatementsResponse` **get** `/v1/instruments/{instrument_id}/cash-flow-statements` Get cash flow statements for an instrument. Retrieves historical cash flow statements for the specified instrument. Cash flow statements show cash inflows and outflows from operating, investing, and financing activities. ### Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID - `from_date: Optional[str]` The start date for the query range, inclusive (YYYY-MM-DD). - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `to_date: Optional[str]` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `class InstrumentDataGetInstrumentCashFlowStatementsResponse: …` - `data: InstrumentCashFlowStatementList` - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `accounts_payables: Optional[str]` Change in accounts payables - `accounts_receivables: Optional[str]` Change in accounts receivables - `acquisitions_net: Optional[str]` Net acquisitions - `capital_expenditure: Optional[str]` Capital expenditure - `cash_at_beginning_of_period: Optional[str]` Cash and cash equivalents at beginning of period - `cash_at_end_of_period: Optional[str]` Cash and cash equivalents at end of period - `change_in_working_capital: Optional[str]` Change in working capital - `common_dividends_paid: Optional[str]` Common dividends paid - `common_stock_issuance: Optional[str]` Common stock issuance - `common_stock_repurchased: Optional[str]` Common stock repurchased (buybacks) - `deferred_income_tax: Optional[str]` Deferred income tax expense - `depreciation_and_amortization: Optional[str]` Depreciation and amortization expense - `effect_of_forex_changes_on_cash: Optional[str]` Effect of foreign exchange changes on cash - `free_cash_flow: Optional[str]` Free cash flow (operating cash flow minus capital expenditure) - `income_taxes_paid: Optional[str]` Income taxes paid - `interest_paid: Optional[str]` Interest paid - `inventory: Optional[str]` Change in inventory - `investments_in_property_plant_and_equipment: Optional[str]` Investments in property, plant, and equipment - `long_term_net_debt_issuance: Optional[str]` Long-term net debt issuance - `net_cash_provided_by_financing_activities: Optional[str]` Net cash provided by financing activities - `net_cash_provided_by_investing_activities: Optional[str]` Net cash provided by investing activities - `net_cash_provided_by_operating_activities: Optional[str]` Net cash provided by operating activities - `net_change_in_cash: Optional[str]` Net change in cash during the period - `net_common_stock_issuance: Optional[str]` Net common stock issuance - `net_debt_issuance: Optional[str]` Net debt issuance (long-term + short-term) - `net_dividends_paid: Optional[str]` Net dividends paid (common + preferred) - `net_income: Optional[str]` Net income for the period - `net_preferred_stock_issuance: Optional[str]` Net preferred stock issuance - `net_stock_issuance: Optional[str]` Net stock issuance (common + preferred) - `operating_cash_flow: Optional[str]` Operating cash flow (alternative calculation) - `other_financing_activities: Optional[str]` Other financing activities - `other_investing_activities: Optional[str]` Other investing activities - `other_non_cash_items: Optional[str]` Other non-cash items - `other_working_capital: Optional[str]` Change in other working capital - `preferred_dividends_paid: Optional[str]` Preferred dividends paid - `purchases_of_investments: Optional[str]` Purchases of investments - `sales_maturities_of_investments: Optional[str]` Sales and maturities of investments - `short_term_net_debt_issuance: Optional[str]` Short-term net debt issuance - `stock_based_compensation: Optional[str]` Stock-based compensation expense ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.get_instrument_cash_flow_statements( instrument_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response) ``` #### Response ```json { "data": [ { "accepted_date": "2025-05-02T14:30:00Z", "capital_expenditure": "-2600000000", "cash_at_beginning_of_period": "33743000000", "cash_at_end_of_period": "29943000000", "change_in_working_capital": "-3200000000", "common_stock_repurchased": "-23000000000", "depreciation_and_amortization": "2900000000", "filing_date": "2025-05-01", "free_cash_flow": "25800000000", "investments_in_property_plant_and_equipment": "-2600000000", "net_cash_provided_by_financing_activities": "-28300000000", "net_cash_provided_by_investing_activities": "-3900000000", "net_cash_provided_by_operating_activities": "28400000000", "net_change_in_cash": "-3800000000", "net_debt_issuance": "-1500000000", "net_dividends_paid": "-3800000000", "net_income": "22200000000", "operating_cash_flow": "28400000000", "period": "Q1", "period_type": "QUARTERLY", "purchases_of_investments": "-9500000000", "reported_currency": "USD", "sales_maturities_of_investments": "8200000000", "stock_based_compensation": "2500000000", "year": 2025 } ], "error": null, "metadata": { "next_page_token": "AAAAAAAAAGQAAAAAAAAAZQ==", "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "total_items": 20, "total_pages": 2 } } ``` ## Domain Types ### All Events Event Type - `Literal["EARNINGS", "DIVIDEND", "STOCK_SPLIT", "IPO"]` Event types supported by the all-events endpoint. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` ### Analyst Distribution - `class AnalystDistribution: …` Analyst recommendation distribution - `buy: int` Number of buy recommendations - `hold: int` Number of hold recommendations - `sell: int` Number of sell recommendations - `strong_buy: int` Number of strong buy recommendations - `strong_sell: int` Number of strong sell recommendations ### Analyst Rating - `Literal["STRONG_BUY", "BUY", "HOLD", 2 more]` Analyst rating category - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Fiscal Period Type - `Literal["QUARTERLY", "ANNUAL", "TTM", "BIANNUAL"]` Fiscal period type for earnings reports - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` ### Instrument All Events Data - `class InstrumentAllEventsData: …` All-events payload grouped by date. - `event_dates: List[InstrumentEventsByDate]` Events grouped by date in descending order. - `date: date` Event date. - `events: List[InstrumentEventEnvelope]` Flat event envelopes for this date. - `symbol: str` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: Optional[InstrumentDividendEvent]` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: str` The adjusted dividend amount accounting for any splits. - `ex_date: date` The day the stock starts trading without the right to receive that dividend. - `declaration_date: Optional[date]` The declaration date of the dividend - `dividend_amount: Optional[str]` The dividend amount per share. - `dividend_yield: Optional[str]` The dividend yield as a percentage of the stock price. - `frequency: Optional[str]` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: Optional[date]` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: Optional[date]` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: Optional[InstrumentEarnings]` Earnings payload when type is EARNINGS. - `date: date` The date when the earnings report was published - `eps_actual: Optional[str]` The actual earnings per share (EPS) for the period - `eps_estimate: Optional[str]` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: Optional[str]` The percentage difference between actual and estimated EPS - `revenue_actual: Optional[str]` The actual total revenue for the period - `revenue_estimate: Optional[str]` The estimated total revenue for the period - `revenue_surprise_percent: Optional[str]` The percentage difference between actual and estimated revenue - `instrument_id: Optional[str]` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: Optional[InstrumentEventIpoItem]` IPO payload when type is IPO. - `actions: Optional[str]` IPO action. - `announced_at: Optional[datetime]` IPO announced timestamp. - `company: Optional[str]` IPO company name. - `exchange: Optional[str]` IPO exchange. - `market_cap: Optional[str]` IPO market cap. - `price_range: Optional[str]` IPO price range. - `shares: Optional[str]` IPO shares offered. - `name: Optional[str]` Instrument name associated with the event, when available. - `reporting_currency: Optional[str]` The currency used for reporting financial data. - `stock_split_event_data: Optional[InstrumentSplitEvent]` Stock split payload when type is STOCK_SPLIT. - `date: date` The date of the stock split - `denominator: str` The denominator of the split ratio - `numerator: str` The numerator of the split ratio - `split_type: str` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Instrument Analyst Consensus - `class InstrumentAnalystConsensus: …` Aggregated analyst consensus metrics - `date: date` The date the consensus snapshot was generated - `distribution: Optional[AnalystDistribution]` Count of individual analyst recommendations by category - `buy: int` Number of buy recommendations - `hold: int` Number of hold recommendations - `sell: int` Number of sell recommendations - `strong_buy: int` Number of strong buy recommendations - `strong_sell: int` Number of strong sell recommendations - `price_target: Optional[PriceTarget]` Aggregated analyst price target statistics - `average: str` Average analyst price target - `currency: str` ISO 4217 currency code of the price targets - `high: str` Highest analyst price target - `low: str` Lowest analyst price target - `rating: Optional[AnalystRating]` Consensus analyst rating - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Instrument Balance Sheet Statement - `class InstrumentBalanceSheetStatement: …` A quarterly balance sheet statement for an instrument. - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `account_payables: Optional[str]` Account payables - `accounts_receivables: Optional[str]` Accounts receivables - `accrued_expenses: Optional[str]` Accrued expenses - `accumulated_other_comprehensive_income_loss: Optional[str]` Accumulated other comprehensive income/loss - `additional_paid_in_capital: Optional[str]` Additional paid-in capital - `capital_lease_obligations: Optional[str]` Capital lease obligations (total) - `capital_lease_obligations_current: Optional[str]` Capital lease obligations (current portion) - `cash_and_cash_equivalents: Optional[str]` Cash and cash equivalents - `cash_and_short_term_investments: Optional[str]` Cash and short-term investments combined - `common_stock: Optional[str]` Common stock - `deferred_revenue: Optional[str]` Deferred revenue - `deferred_revenue_non_current: Optional[str]` Deferred revenue (non-current) - `deferred_tax_liabilities_non_current: Optional[str]` Deferred tax liabilities (non-current) - `goodwill: Optional[str]` Goodwill - `goodwill_and_intangible_assets: Optional[str]` Goodwill and intangible assets combined - `intangible_assets: Optional[str]` Intangible assets - `inventory: Optional[str]` Inventory - `long_term_debt: Optional[str]` Long-term debt - `long_term_investments: Optional[str]` Long-term investments - `minority_interest: Optional[str]` Minority interest - `net_debt: Optional[str]` Net debt (total debt minus cash) - `net_receivables: Optional[str]` Net receivables - `other_assets: Optional[str]` Other assets - `other_current_assets: Optional[str]` Other current assets - `other_current_liabilities: Optional[str]` Other current liabilities - `other_liabilities: Optional[str]` Other liabilities - `other_non_current_assets: Optional[str]` Other non-current assets - `other_non_current_liabilities: Optional[str]` Other non-current liabilities - `other_payables: Optional[str]` Other payables - `other_receivables: Optional[str]` Other receivables - `other_total_stockholders_equity: Optional[str]` Other total stockholders equity - `preferred_stock: Optional[str]` Preferred stock - `prepaids: Optional[str]` Prepaids - `property_plant_and_equipment_net: Optional[str]` Property, plant and equipment net of depreciation - `retained_earnings: Optional[str]` Retained earnings - `short_term_debt: Optional[str]` Short-term debt - `short_term_investments: Optional[str]` Short-term investments - `tax_assets: Optional[str]` Tax assets - `tax_payables: Optional[str]` Tax payables - `total_assets: Optional[str]` Total assets - `total_current_assets: Optional[str]` Total current assets - `total_current_liabilities: Optional[str]` Total current liabilities - `total_debt: Optional[str]` Total debt - `total_equity: Optional[str]` Total equity - `total_investments: Optional[str]` Total investments - `total_liabilities: Optional[str]` Total liabilities - `total_liabilities_and_total_equity: Optional[str]` Total liabilities and total equity - `total_non_current_assets: Optional[str]` Total non-current assets - `total_non_current_liabilities: Optional[str]` Total non-current liabilities - `total_payables: Optional[str]` Total payables - `total_stockholders_equity: Optional[str]` Total stockholders equity - `treasury_stock: Optional[str]` Treasury stock ### Instrument Balance Sheet Statement List - `List[InstrumentBalanceSheetStatement]` - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `account_payables: Optional[str]` Account payables - `accounts_receivables: Optional[str]` Accounts receivables - `accrued_expenses: Optional[str]` Accrued expenses - `accumulated_other_comprehensive_income_loss: Optional[str]` Accumulated other comprehensive income/loss - `additional_paid_in_capital: Optional[str]` Additional paid-in capital - `capital_lease_obligations: Optional[str]` Capital lease obligations (total) - `capital_lease_obligations_current: Optional[str]` Capital lease obligations (current portion) - `cash_and_cash_equivalents: Optional[str]` Cash and cash equivalents - `cash_and_short_term_investments: Optional[str]` Cash and short-term investments combined - `common_stock: Optional[str]` Common stock - `deferred_revenue: Optional[str]` Deferred revenue - `deferred_revenue_non_current: Optional[str]` Deferred revenue (non-current) - `deferred_tax_liabilities_non_current: Optional[str]` Deferred tax liabilities (non-current) - `goodwill: Optional[str]` Goodwill - `goodwill_and_intangible_assets: Optional[str]` Goodwill and intangible assets combined - `intangible_assets: Optional[str]` Intangible assets - `inventory: Optional[str]` Inventory - `long_term_debt: Optional[str]` Long-term debt - `long_term_investments: Optional[str]` Long-term investments - `minority_interest: Optional[str]` Minority interest - `net_debt: Optional[str]` Net debt (total debt minus cash) - `net_receivables: Optional[str]` Net receivables - `other_assets: Optional[str]` Other assets - `other_current_assets: Optional[str]` Other current assets - `other_current_liabilities: Optional[str]` Other current liabilities - `other_liabilities: Optional[str]` Other liabilities - `other_non_current_assets: Optional[str]` Other non-current assets - `other_non_current_liabilities: Optional[str]` Other non-current liabilities - `other_payables: Optional[str]` Other payables - `other_receivables: Optional[str]` Other receivables - `other_total_stockholders_equity: Optional[str]` Other total stockholders equity - `preferred_stock: Optional[str]` Preferred stock - `prepaids: Optional[str]` Prepaids - `property_plant_and_equipment_net: Optional[str]` Property, plant and equipment net of depreciation - `retained_earnings: Optional[str]` Retained earnings - `short_term_debt: Optional[str]` Short-term debt - `short_term_investments: Optional[str]` Short-term investments - `tax_assets: Optional[str]` Tax assets - `tax_payables: Optional[str]` Tax payables - `total_assets: Optional[str]` Total assets - `total_current_assets: Optional[str]` Total current assets - `total_current_liabilities: Optional[str]` Total current liabilities - `total_debt: Optional[str]` Total debt - `total_equity: Optional[str]` Total equity - `total_investments: Optional[str]` Total investments - `total_liabilities: Optional[str]` Total liabilities - `total_liabilities_and_total_equity: Optional[str]` Total liabilities and total equity - `total_non_current_assets: Optional[str]` Total non-current assets - `total_non_current_liabilities: Optional[str]` Total non-current liabilities - `total_payables: Optional[str]` Total payables - `total_stockholders_equity: Optional[str]` Total stockholders equity - `treasury_stock: Optional[str]` Treasury stock ### Instrument Cash Flow Statement - `class InstrumentCashFlowStatement: …` A quarterly cash flow statement for an instrument. - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `accounts_payables: Optional[str]` Change in accounts payables - `accounts_receivables: Optional[str]` Change in accounts receivables - `acquisitions_net: Optional[str]` Net acquisitions - `capital_expenditure: Optional[str]` Capital expenditure - `cash_at_beginning_of_period: Optional[str]` Cash and cash equivalents at beginning of period - `cash_at_end_of_period: Optional[str]` Cash and cash equivalents at end of period - `change_in_working_capital: Optional[str]` Change in working capital - `common_dividends_paid: Optional[str]` Common dividends paid - `common_stock_issuance: Optional[str]` Common stock issuance - `common_stock_repurchased: Optional[str]` Common stock repurchased (buybacks) - `deferred_income_tax: Optional[str]` Deferred income tax expense - `depreciation_and_amortization: Optional[str]` Depreciation and amortization expense - `effect_of_forex_changes_on_cash: Optional[str]` Effect of foreign exchange changes on cash - `free_cash_flow: Optional[str]` Free cash flow (operating cash flow minus capital expenditure) - `income_taxes_paid: Optional[str]` Income taxes paid - `interest_paid: Optional[str]` Interest paid - `inventory: Optional[str]` Change in inventory - `investments_in_property_plant_and_equipment: Optional[str]` Investments in property, plant, and equipment - `long_term_net_debt_issuance: Optional[str]` Long-term net debt issuance - `net_cash_provided_by_financing_activities: Optional[str]` Net cash provided by financing activities - `net_cash_provided_by_investing_activities: Optional[str]` Net cash provided by investing activities - `net_cash_provided_by_operating_activities: Optional[str]` Net cash provided by operating activities - `net_change_in_cash: Optional[str]` Net change in cash during the period - `net_common_stock_issuance: Optional[str]` Net common stock issuance - `net_debt_issuance: Optional[str]` Net debt issuance (long-term + short-term) - `net_dividends_paid: Optional[str]` Net dividends paid (common + preferred) - `net_income: Optional[str]` Net income for the period - `net_preferred_stock_issuance: Optional[str]` Net preferred stock issuance - `net_stock_issuance: Optional[str]` Net stock issuance (common + preferred) - `operating_cash_flow: Optional[str]` Operating cash flow (alternative calculation) - `other_financing_activities: Optional[str]` Other financing activities - `other_investing_activities: Optional[str]` Other investing activities - `other_non_cash_items: Optional[str]` Other non-cash items - `other_working_capital: Optional[str]` Change in other working capital - `preferred_dividends_paid: Optional[str]` Preferred dividends paid - `purchases_of_investments: Optional[str]` Purchases of investments - `sales_maturities_of_investments: Optional[str]` Sales and maturities of investments - `short_term_net_debt_issuance: Optional[str]` Short-term net debt issuance - `stock_based_compensation: Optional[str]` Stock-based compensation expense ### Instrument Cash Flow Statement List - `List[InstrumentCashFlowStatement]` - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `accounts_payables: Optional[str]` Change in accounts payables - `accounts_receivables: Optional[str]` Change in accounts receivables - `acquisitions_net: Optional[str]` Net acquisitions - `capital_expenditure: Optional[str]` Capital expenditure - `cash_at_beginning_of_period: Optional[str]` Cash and cash equivalents at beginning of period - `cash_at_end_of_period: Optional[str]` Cash and cash equivalents at end of period - `change_in_working_capital: Optional[str]` Change in working capital - `common_dividends_paid: Optional[str]` Common dividends paid - `common_stock_issuance: Optional[str]` Common stock issuance - `common_stock_repurchased: Optional[str]` Common stock repurchased (buybacks) - `deferred_income_tax: Optional[str]` Deferred income tax expense - `depreciation_and_amortization: Optional[str]` Depreciation and amortization expense - `effect_of_forex_changes_on_cash: Optional[str]` Effect of foreign exchange changes on cash - `free_cash_flow: Optional[str]` Free cash flow (operating cash flow minus capital expenditure) - `income_taxes_paid: Optional[str]` Income taxes paid - `interest_paid: Optional[str]` Interest paid - `inventory: Optional[str]` Change in inventory - `investments_in_property_plant_and_equipment: Optional[str]` Investments in property, plant, and equipment - `long_term_net_debt_issuance: Optional[str]` Long-term net debt issuance - `net_cash_provided_by_financing_activities: Optional[str]` Net cash provided by financing activities - `net_cash_provided_by_investing_activities: Optional[str]` Net cash provided by investing activities - `net_cash_provided_by_operating_activities: Optional[str]` Net cash provided by operating activities - `net_change_in_cash: Optional[str]` Net change in cash during the period - `net_common_stock_issuance: Optional[str]` Net common stock issuance - `net_debt_issuance: Optional[str]` Net debt issuance (long-term + short-term) - `net_dividends_paid: Optional[str]` Net dividends paid (common + preferred) - `net_income: Optional[str]` Net income for the period - `net_preferred_stock_issuance: Optional[str]` Net preferred stock issuance - `net_stock_issuance: Optional[str]` Net stock issuance (common + preferred) - `operating_cash_flow: Optional[str]` Operating cash flow (alternative calculation) - `other_financing_activities: Optional[str]` Other financing activities - `other_investing_activities: Optional[str]` Other investing activities - `other_non_cash_items: Optional[str]` Other non-cash items - `other_working_capital: Optional[str]` Change in other working capital - `preferred_dividends_paid: Optional[str]` Preferred dividends paid - `purchases_of_investments: Optional[str]` Purchases of investments - `sales_maturities_of_investments: Optional[str]` Sales and maturities of investments - `short_term_net_debt_issuance: Optional[str]` Short-term net debt issuance - `stock_based_compensation: Optional[str]` Stock-based compensation expense ### Instrument Dividend Event - `class InstrumentDividendEvent: …` Represents a dividend event for an instrument - `adjusted_dividend_amount: str` The adjusted dividend amount accounting for any splits. - `ex_date: date` The day the stock starts trading without the right to receive that dividend. - `declaration_date: Optional[date]` The declaration date of the dividend - `dividend_amount: Optional[str]` The dividend amount per share. - `dividend_yield: Optional[str]` The dividend yield as a percentage of the stock price. - `frequency: Optional[str]` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: Optional[date]` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: Optional[date]` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. ### Instrument Earnings - `class InstrumentEarnings: …` Represents instrument earnings data - `date: date` The date when the earnings report was published - `eps_actual: Optional[str]` The actual earnings per share (EPS) for the period - `eps_estimate: Optional[str]` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: Optional[str]` The percentage difference between actual and estimated EPS - `revenue_actual: Optional[str]` The actual total revenue for the period - `revenue_estimate: Optional[str]` The estimated total revenue for the period - `revenue_surprise_percent: Optional[str]` The percentage difference between actual and estimated revenue ### Instrument Event Envelope - `class InstrumentEventEnvelope: …` Unified envelope for the all-events response. - `symbol: str` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: Optional[InstrumentDividendEvent]` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: str` The adjusted dividend amount accounting for any splits. - `ex_date: date` The day the stock starts trading without the right to receive that dividend. - `declaration_date: Optional[date]` The declaration date of the dividend - `dividend_amount: Optional[str]` The dividend amount per share. - `dividend_yield: Optional[str]` The dividend yield as a percentage of the stock price. - `frequency: Optional[str]` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: Optional[date]` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: Optional[date]` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: Optional[InstrumentEarnings]` Earnings payload when type is EARNINGS. - `date: date` The date when the earnings report was published - `eps_actual: Optional[str]` The actual earnings per share (EPS) for the period - `eps_estimate: Optional[str]` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: Optional[str]` The percentage difference between actual and estimated EPS - `revenue_actual: Optional[str]` The actual total revenue for the period - `revenue_estimate: Optional[str]` The estimated total revenue for the period - `revenue_surprise_percent: Optional[str]` The percentage difference between actual and estimated revenue - `instrument_id: Optional[str]` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: Optional[InstrumentEventIpoItem]` IPO payload when type is IPO. - `actions: Optional[str]` IPO action. - `announced_at: Optional[datetime]` IPO announced timestamp. - `company: Optional[str]` IPO company name. - `exchange: Optional[str]` IPO exchange. - `market_cap: Optional[str]` IPO market cap. - `price_range: Optional[str]` IPO price range. - `shares: Optional[str]` IPO shares offered. - `name: Optional[str]` Instrument name associated with the event, when available. - `reporting_currency: Optional[str]` The currency used for reporting financial data. - `stock_split_event_data: Optional[InstrumentSplitEvent]` Stock split payload when type is STOCK_SPLIT. - `date: date` The date of the stock split - `denominator: str` The denominator of the split ratio - `numerator: str` The numerator of the split ratio - `split_type: str` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Instrument Event Ipo Item - `class InstrumentEventIpoItem: …` IPO event in the all-events date grouping response. - `actions: Optional[str]` IPO action. - `announced_at: Optional[datetime]` IPO announced timestamp. - `company: Optional[str]` IPO company name. - `exchange: Optional[str]` IPO exchange. - `market_cap: Optional[str]` IPO market cap. - `price_range: Optional[str]` IPO price range. - `shares: Optional[str]` IPO shares offered. ### Instrument Events By Date - `class InstrumentEventsByDate: …` Instrument events for a single date. - `date: date` Event date. - `events: List[InstrumentEventEnvelope]` Flat event envelopes for this date. - `symbol: str` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: Optional[InstrumentDividendEvent]` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: str` The adjusted dividend amount accounting for any splits. - `ex_date: date` The day the stock starts trading without the right to receive that dividend. - `declaration_date: Optional[date]` The declaration date of the dividend - `dividend_amount: Optional[str]` The dividend amount per share. - `dividend_yield: Optional[str]` The dividend yield as a percentage of the stock price. - `frequency: Optional[str]` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: Optional[date]` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: Optional[date]` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: Optional[InstrumentEarnings]` Earnings payload when type is EARNINGS. - `date: date` The date when the earnings report was published - `eps_actual: Optional[str]` The actual earnings per share (EPS) for the period - `eps_estimate: Optional[str]` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: Optional[str]` The percentage difference between actual and estimated EPS - `revenue_actual: Optional[str]` The actual total revenue for the period - `revenue_estimate: Optional[str]` The estimated total revenue for the period - `revenue_surprise_percent: Optional[str]` The percentage difference between actual and estimated revenue - `instrument_id: Optional[str]` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: Optional[InstrumentEventIpoItem]` IPO payload when type is IPO. - `actions: Optional[str]` IPO action. - `announced_at: Optional[datetime]` IPO announced timestamp. - `company: Optional[str]` IPO company name. - `exchange: Optional[str]` IPO exchange. - `market_cap: Optional[str]` IPO market cap. - `price_range: Optional[str]` IPO price range. - `shares: Optional[str]` IPO shares offered. - `name: Optional[str]` Instrument name associated with the event, when available. - `reporting_currency: Optional[str]` The currency used for reporting financial data. - `stock_split_event_data: Optional[InstrumentSplitEvent]` Stock split payload when type is STOCK_SPLIT. - `date: date` The date of the stock split - `denominator: str` The denominator of the split ratio - `numerator: str` The numerator of the split ratio - `split_type: str` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Instrument Events Data - `class InstrumentEventsData: …` Grouped instrument events by type - `dividends: List[InstrumentDividendEvent]` Dividend distribution events - `adjusted_dividend_amount: str` The adjusted dividend amount accounting for any splits. - `ex_date: date` The day the stock starts trading without the right to receive that dividend. - `declaration_date: Optional[date]` The declaration date of the dividend - `dividend_amount: Optional[str]` The dividend amount per share. - `dividend_yield: Optional[str]` The dividend yield as a percentage of the stock price. - `frequency: Optional[str]` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: Optional[date]` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: Optional[date]` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings: List[InstrumentEarnings]` Earnings announcement events - `date: date` The date when the earnings report was published - `eps_actual: Optional[str]` The actual earnings per share (EPS) for the period - `eps_estimate: Optional[str]` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: Optional[str]` The percentage difference between actual and estimated EPS - `revenue_actual: Optional[str]` The actual total revenue for the period - `revenue_estimate: Optional[str]` The estimated total revenue for the period - `revenue_surprise_percent: Optional[str]` The percentage difference between actual and estimated revenue - `instrument_id: str` OEMS instrument UUID from the request - `splits: List[InstrumentSplitEvent]` Stock split events - `date: date` The date of the stock split - `denominator: str` The denominator of the split ratio - `numerator: str` The numerator of the split ratio - `split_type: str` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") - `reporting_currency: Optional[str]` The currency used for reporting financial data ### Instrument Fundamentals - `class InstrumentFundamentals: …` Supplemental fundamentals and company profile data for an instrument. - `average_volume: Optional[int]` The average daily trading volume over the past 30 days - `beta: Optional[str]` The beta value, measuring the instrument's volatility relative to the overall market - `description: Optional[str]` A detailed description of the instrument or company - `dividend_yield: Optional[str]` The trailing twelve months (TTM) dividend yield - `earnings_per_share: Optional[str]` The trailing twelve months (TTM) earnings per share - `fifty_two_week_high: Optional[str]` The highest price over the last 52 weeks - `fifty_two_week_low: Optional[str]` The lowest price over the last 52 weeks - `industry: Optional[str]` The specific industry of the instrument's issuer - `list_date: Optional[date]` The date the instrument was first listed - `logo_url: Optional[str]` URL to a representative logo image for the instrument or issuer - `market_cap: Optional[str]` The total market capitalization - `previous_close: Optional[str]` The closing price from the previous trading day - `price_to_earnings: Optional[str]` The price-to-earnings (P/E) ratio for the trailing twelve months (TTM) - `reporting_currency: Optional[str]` The currency used for reporting financial data - `sector: Optional[str]` The business sector of the instrument's issuer ### Instrument Income Statement - `class InstrumentIncomeStatement: …` A quarterly income statement for an instrument. - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `bottom_line_net_income: Optional[str]` Bottom line net income after all adjustments - `cost_and_expenses: Optional[str]` Total costs and expenses - `cost_of_revenue: Optional[str]` Direct costs attributable to producing goods sold - `depreciation_and_amortization: Optional[str]` Depreciation and amortization expenses - `ebit: Optional[str]` Earnings before interest and taxes - `ebitda: Optional[str]` Earnings before interest, taxes, depreciation, and amortization - `eps: Optional[str]` Basic earnings per share - `eps_diluted: Optional[str]` Diluted earnings per share - `general_and_administrative_expenses: Optional[str]` General administrative overhead expenses - `gross_profit: Optional[str]` Revenue minus cost of revenue - `income_before_tax: Optional[str]` Income before income tax expense - `income_tax_expense: Optional[str]` Income tax expense for the period - `interest_expense: Optional[str]` Interest paid on debt - `interest_income: Optional[str]` Interest earned on investments and cash - `net_income: Optional[str]` Total net income for the period - `net_income_deductions: Optional[str]` Deductions from net income - `net_income_from_continuing_operations: Optional[str]` Net income from continuing operations - `net_income_from_discontinued_operations: Optional[str]` Net income from discontinued operations - `net_interest_income: Optional[str]` Net interest income (interest income minus interest expense) - `non_operating_income_excluding_interest: Optional[str]` Non-operating income excluding interest - `operating_expenses: Optional[str]` Total operating expenses - `operating_income: Optional[str]` Income from core business operations - `other_adjustments_to_net_income: Optional[str]` Other adjustments to net income - `other_expenses: Optional[str]` Other miscellaneous expenses - `research_and_development_expenses: Optional[str]` Expenditure on research and development activities - `revenue: Optional[str]` Total revenue from sales of goods and services - `selling_and_marketing_expenses: Optional[str]` Expenditure on marketing and sales activities - `selling_general_and_administrative_expenses: Optional[str]` Combined selling, general, and administrative expenses - `total_other_income_expenses_net: Optional[str]` Net of other income and expenses - `weighted_average_shs_out: Optional[str]` Weighted average shares outstanding (basic) - `weighted_average_shs_out_dil: Optional[str]` Weighted average shares outstanding (diluted) ### Instrument Income Statement List - `List[InstrumentIncomeStatement]` - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `bottom_line_net_income: Optional[str]` Bottom line net income after all adjustments - `cost_and_expenses: Optional[str]` Total costs and expenses - `cost_of_revenue: Optional[str]` Direct costs attributable to producing goods sold - `depreciation_and_amortization: Optional[str]` Depreciation and amortization expenses - `ebit: Optional[str]` Earnings before interest and taxes - `ebitda: Optional[str]` Earnings before interest, taxes, depreciation, and amortization - `eps: Optional[str]` Basic earnings per share - `eps_diluted: Optional[str]` Diluted earnings per share - `general_and_administrative_expenses: Optional[str]` General administrative overhead expenses - `gross_profit: Optional[str]` Revenue minus cost of revenue - `income_before_tax: Optional[str]` Income before income tax expense - `income_tax_expense: Optional[str]` Income tax expense for the period - `interest_expense: Optional[str]` Interest paid on debt - `interest_income: Optional[str]` Interest earned on investments and cash - `net_income: Optional[str]` Total net income for the period - `net_income_deductions: Optional[str]` Deductions from net income - `net_income_from_continuing_operations: Optional[str]` Net income from continuing operations - `net_income_from_discontinued_operations: Optional[str]` Net income from discontinued operations - `net_interest_income: Optional[str]` Net interest income (interest income minus interest expense) - `non_operating_income_excluding_interest: Optional[str]` Non-operating income excluding interest - `operating_expenses: Optional[str]` Total operating expenses - `operating_income: Optional[str]` Income from core business operations - `other_adjustments_to_net_income: Optional[str]` Other adjustments to net income - `other_expenses: Optional[str]` Other miscellaneous expenses - `research_and_development_expenses: Optional[str]` Expenditure on research and development activities - `revenue: Optional[str]` Total revenue from sales of goods and services - `selling_and_marketing_expenses: Optional[str]` Expenditure on marketing and sales activities - `selling_general_and_administrative_expenses: Optional[str]` Combined selling, general, and administrative expenses - `total_other_income_expenses_net: Optional[str]` Net of other income and expenses - `weighted_average_shs_out: Optional[str]` Weighted average shares outstanding (basic) - `weighted_average_shs_out_dil: Optional[str]` Weighted average shares outstanding (diluted) ### Instrument Split Event - `class InstrumentSplitEvent: …` Represents a stock split event for an instrument - `date: date` The date of the stock split - `denominator: str` The denominator of the split ratio - `numerator: str` The numerator of the split ratio - `split_type: str` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Price Target - `class PriceTarget: …` Analyst price target statistics - `average: str` Average analyst price target - `currency: str` ISO 4217 currency code of the price targets - `high: str` Highest analyst price target - `low: str` Lowest analyst price target ### Instrument Data Get All Instrument Events Response - `class InstrumentDataGetAllInstrumentEventsResponse: …` - `data: InstrumentAllEventsData` All-events payload grouped by date. - `event_dates: List[InstrumentEventsByDate]` Events grouped by date in descending order. - `date: date` Event date. - `events: List[InstrumentEventEnvelope]` Flat event envelopes for this date. - `symbol: str` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: Optional[InstrumentDividendEvent]` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: str` The adjusted dividend amount accounting for any splits. - `ex_date: date` The day the stock starts trading without the right to receive that dividend. - `declaration_date: Optional[date]` The declaration date of the dividend - `dividend_amount: Optional[str]` The dividend amount per share. - `dividend_yield: Optional[str]` The dividend yield as a percentage of the stock price. - `frequency: Optional[str]` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: Optional[date]` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: Optional[date]` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: Optional[InstrumentEarnings]` Earnings payload when type is EARNINGS. - `date: date` The date when the earnings report was published - `eps_actual: Optional[str]` The actual earnings per share (EPS) for the period - `eps_estimate: Optional[str]` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: Optional[str]` The percentage difference between actual and estimated EPS - `revenue_actual: Optional[str]` The actual total revenue for the period - `revenue_estimate: Optional[str]` The estimated total revenue for the period - `revenue_surprise_percent: Optional[str]` The percentage difference between actual and estimated revenue - `instrument_id: Optional[str]` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: Optional[InstrumentEventIpoItem]` IPO payload when type is IPO. - `actions: Optional[str]` IPO action. - `announced_at: Optional[datetime]` IPO announced timestamp. - `company: Optional[str]` IPO company name. - `exchange: Optional[str]` IPO exchange. - `market_cap: Optional[str]` IPO market cap. - `price_range: Optional[str]` IPO price range. - `shares: Optional[str]` IPO shares offered. - `name: Optional[str]` Instrument name associated with the event, when available. - `reporting_currency: Optional[str]` The currency used for reporting financial data. - `stock_split_event_data: Optional[InstrumentSplitEvent]` Stock split payload when type is STOCK_SPLIT. - `date: date` The date of the stock split - `denominator: str` The denominator of the split ratio - `numerator: str` The numerator of the split ratio - `split_type: str` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Instrument Data Get Instrument Events Response - `class InstrumentDataGetInstrumentEventsResponse: …` - `data: InstrumentEventsData` Grouped instrument events by type - `dividends: List[InstrumentDividendEvent]` Dividend distribution events - `adjusted_dividend_amount: str` The adjusted dividend amount accounting for any splits. - `ex_date: date` The day the stock starts trading without the right to receive that dividend. - `declaration_date: Optional[date]` The declaration date of the dividend - `dividend_amount: Optional[str]` The dividend amount per share. - `dividend_yield: Optional[str]` The dividend yield as a percentage of the stock price. - `frequency: Optional[str]` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: Optional[date]` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: Optional[date]` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings: List[InstrumentEarnings]` Earnings announcement events - `date: date` The date when the earnings report was published - `eps_actual: Optional[str]` The actual earnings per share (EPS) for the period - `eps_estimate: Optional[str]` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: Optional[str]` The percentage difference between actual and estimated EPS - `revenue_actual: Optional[str]` The actual total revenue for the period - `revenue_estimate: Optional[str]` The estimated total revenue for the period - `revenue_surprise_percent: Optional[str]` The percentage difference between actual and estimated revenue - `instrument_id: str` OEMS instrument UUID from the request - `splits: List[InstrumentSplitEvent]` Stock split events - `date: date` The date of the stock split - `denominator: str` The denominator of the split ratio - `numerator: str` The numerator of the split ratio - `split_type: str` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") - `reporting_currency: Optional[str]` The currency used for reporting financial data ### Instrument Data Get Instrument Fundamentals Response - `class InstrumentDataGetInstrumentFundamentalsResponse: …` - `data: InstrumentFundamentals` Supplemental fundamentals and company profile data for an instrument. - `average_volume: Optional[int]` The average daily trading volume over the past 30 days - `beta: Optional[str]` The beta value, measuring the instrument's volatility relative to the overall market - `description: Optional[str]` A detailed description of the instrument or company - `dividend_yield: Optional[str]` The trailing twelve months (TTM) dividend yield - `earnings_per_share: Optional[str]` The trailing twelve months (TTM) earnings per share - `fifty_two_week_high: Optional[str]` The highest price over the last 52 weeks - `fifty_two_week_low: Optional[str]` The lowest price over the last 52 weeks - `industry: Optional[str]` The specific industry of the instrument's issuer - `list_date: Optional[date]` The date the instrument was first listed - `logo_url: Optional[str]` URL to a representative logo image for the instrument or issuer - `market_cap: Optional[str]` The total market capitalization - `previous_close: Optional[str]` The closing price from the previous trading day - `price_to_earnings: Optional[str]` The price-to-earnings (P/E) ratio for the trailing twelve months (TTM) - `reporting_currency: Optional[str]` The currency used for reporting financial data - `sector: Optional[str]` The business sector of the instrument's issuer ### Instrument Data Get Instrument Balance Sheet Statements Response - `class InstrumentDataGetInstrumentBalanceSheetStatementsResponse: …` - `data: InstrumentBalanceSheetStatementList` - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `account_payables: Optional[str]` Account payables - `accounts_receivables: Optional[str]` Accounts receivables - `accrued_expenses: Optional[str]` Accrued expenses - `accumulated_other_comprehensive_income_loss: Optional[str]` Accumulated other comprehensive income/loss - `additional_paid_in_capital: Optional[str]` Additional paid-in capital - `capital_lease_obligations: Optional[str]` Capital lease obligations (total) - `capital_lease_obligations_current: Optional[str]` Capital lease obligations (current portion) - `cash_and_cash_equivalents: Optional[str]` Cash and cash equivalents - `cash_and_short_term_investments: Optional[str]` Cash and short-term investments combined - `common_stock: Optional[str]` Common stock - `deferred_revenue: Optional[str]` Deferred revenue - `deferred_revenue_non_current: Optional[str]` Deferred revenue (non-current) - `deferred_tax_liabilities_non_current: Optional[str]` Deferred tax liabilities (non-current) - `goodwill: Optional[str]` Goodwill - `goodwill_and_intangible_assets: Optional[str]` Goodwill and intangible assets combined - `intangible_assets: Optional[str]` Intangible assets - `inventory: Optional[str]` Inventory - `long_term_debt: Optional[str]` Long-term debt - `long_term_investments: Optional[str]` Long-term investments - `minority_interest: Optional[str]` Minority interest - `net_debt: Optional[str]` Net debt (total debt minus cash) - `net_receivables: Optional[str]` Net receivables - `other_assets: Optional[str]` Other assets - `other_current_assets: Optional[str]` Other current assets - `other_current_liabilities: Optional[str]` Other current liabilities - `other_liabilities: Optional[str]` Other liabilities - `other_non_current_assets: Optional[str]` Other non-current assets - `other_non_current_liabilities: Optional[str]` Other non-current liabilities - `other_payables: Optional[str]` Other payables - `other_receivables: Optional[str]` Other receivables - `other_total_stockholders_equity: Optional[str]` Other total stockholders equity - `preferred_stock: Optional[str]` Preferred stock - `prepaids: Optional[str]` Prepaids - `property_plant_and_equipment_net: Optional[str]` Property, plant and equipment net of depreciation - `retained_earnings: Optional[str]` Retained earnings - `short_term_debt: Optional[str]` Short-term debt - `short_term_investments: Optional[str]` Short-term investments - `tax_assets: Optional[str]` Tax assets - `tax_payables: Optional[str]` Tax payables - `total_assets: Optional[str]` Total assets - `total_current_assets: Optional[str]` Total current assets - `total_current_liabilities: Optional[str]` Total current liabilities - `total_debt: Optional[str]` Total debt - `total_equity: Optional[str]` Total equity - `total_investments: Optional[str]` Total investments - `total_liabilities: Optional[str]` Total liabilities - `total_liabilities_and_total_equity: Optional[str]` Total liabilities and total equity - `total_non_current_assets: Optional[str]` Total non-current assets - `total_non_current_liabilities: Optional[str]` Total non-current liabilities - `total_payables: Optional[str]` Total payables - `total_stockholders_equity: Optional[str]` Total stockholders equity - `treasury_stock: Optional[str]` Treasury stock ### Instrument Data Get Instrument Income Statements Response - `class InstrumentDataGetInstrumentIncomeStatementsResponse: …` - `data: InstrumentIncomeStatementList` - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `bottom_line_net_income: Optional[str]` Bottom line net income after all adjustments - `cost_and_expenses: Optional[str]` Total costs and expenses - `cost_of_revenue: Optional[str]` Direct costs attributable to producing goods sold - `depreciation_and_amortization: Optional[str]` Depreciation and amortization expenses - `ebit: Optional[str]` Earnings before interest and taxes - `ebitda: Optional[str]` Earnings before interest, taxes, depreciation, and amortization - `eps: Optional[str]` Basic earnings per share - `eps_diluted: Optional[str]` Diluted earnings per share - `general_and_administrative_expenses: Optional[str]` General administrative overhead expenses - `gross_profit: Optional[str]` Revenue minus cost of revenue - `income_before_tax: Optional[str]` Income before income tax expense - `income_tax_expense: Optional[str]` Income tax expense for the period - `interest_expense: Optional[str]` Interest paid on debt - `interest_income: Optional[str]` Interest earned on investments and cash - `net_income: Optional[str]` Total net income for the period - `net_income_deductions: Optional[str]` Deductions from net income - `net_income_from_continuing_operations: Optional[str]` Net income from continuing operations - `net_income_from_discontinued_operations: Optional[str]` Net income from discontinued operations - `net_interest_income: Optional[str]` Net interest income (interest income minus interest expense) - `non_operating_income_excluding_interest: Optional[str]` Non-operating income excluding interest - `operating_expenses: Optional[str]` Total operating expenses - `operating_income: Optional[str]` Income from core business operations - `other_adjustments_to_net_income: Optional[str]` Other adjustments to net income - `other_expenses: Optional[str]` Other miscellaneous expenses - `research_and_development_expenses: Optional[str]` Expenditure on research and development activities - `revenue: Optional[str]` Total revenue from sales of goods and services - `selling_and_marketing_expenses: Optional[str]` Expenditure on marketing and sales activities - `selling_general_and_administrative_expenses: Optional[str]` Combined selling, general, and administrative expenses - `total_other_income_expenses_net: Optional[str]` Net of other income and expenses - `weighted_average_shs_out: Optional[str]` Weighted average shares outstanding (basic) - `weighted_average_shs_out_dil: Optional[str]` Weighted average shares outstanding (diluted) ### Instrument Data Get Instrument Analyst Consensus Response - `class InstrumentDataGetInstrumentAnalystConsensusResponse: …` - `data: InstrumentAnalystConsensus` Aggregated analyst consensus metrics - `date: date` The date the consensus snapshot was generated - `distribution: Optional[AnalystDistribution]` Count of individual analyst recommendations by category - `buy: int` Number of buy recommendations - `hold: int` Number of hold recommendations - `sell: int` Number of sell recommendations - `strong_buy: int` Number of strong buy recommendations - `strong_sell: int` Number of strong sell recommendations - `price_target: Optional[PriceTarget]` Aggregated analyst price target statistics - `average: str` Average analyst price target - `currency: str` ISO 4217 currency code of the price targets - `high: str` Highest analyst price target - `low: str` Lowest analyst price target - `rating: Optional[AnalystRating]` Consensus analyst rating - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Instrument Data Get Instrument Cash Flow Statements Response - `class InstrumentDataGetInstrumentCashFlowStatementsResponse: …` - `data: InstrumentCashFlowStatementList` - `accepted_date: datetime` The date and time when the filing was accepted by the SEC - `filing_date: date` The date the financial statement was filed - `period: str` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: str` The currency in which the statement is reported (ISO 4217) - `year: int` The fiscal year of the statement - `accounts_payables: Optional[str]` Change in accounts payables - `accounts_receivables: Optional[str]` Change in accounts receivables - `acquisitions_net: Optional[str]` Net acquisitions - `capital_expenditure: Optional[str]` Capital expenditure - `cash_at_beginning_of_period: Optional[str]` Cash and cash equivalents at beginning of period - `cash_at_end_of_period: Optional[str]` Cash and cash equivalents at end of period - `change_in_working_capital: Optional[str]` Change in working capital - `common_dividends_paid: Optional[str]` Common dividends paid - `common_stock_issuance: Optional[str]` Common stock issuance - `common_stock_repurchased: Optional[str]` Common stock repurchased (buybacks) - `deferred_income_tax: Optional[str]` Deferred income tax expense - `depreciation_and_amortization: Optional[str]` Depreciation and amortization expense - `effect_of_forex_changes_on_cash: Optional[str]` Effect of foreign exchange changes on cash - `free_cash_flow: Optional[str]` Free cash flow (operating cash flow minus capital expenditure) - `income_taxes_paid: Optional[str]` Income taxes paid - `interest_paid: Optional[str]` Interest paid - `inventory: Optional[str]` Change in inventory - `investments_in_property_plant_and_equipment: Optional[str]` Investments in property, plant, and equipment - `long_term_net_debt_issuance: Optional[str]` Long-term net debt issuance - `net_cash_provided_by_financing_activities: Optional[str]` Net cash provided by financing activities - `net_cash_provided_by_investing_activities: Optional[str]` Net cash provided by investing activities - `net_cash_provided_by_operating_activities: Optional[str]` Net cash provided by operating activities - `net_change_in_cash: Optional[str]` Net change in cash during the period - `net_common_stock_issuance: Optional[str]` Net common stock issuance - `net_debt_issuance: Optional[str]` Net debt issuance (long-term + short-term) - `net_dividends_paid: Optional[str]` Net dividends paid (common + preferred) - `net_income: Optional[str]` Net income for the period - `net_preferred_stock_issuance: Optional[str]` Net preferred stock issuance - `net_stock_issuance: Optional[str]` Net stock issuance (common + preferred) - `operating_cash_flow: Optional[str]` Operating cash flow (alternative calculation) - `other_financing_activities: Optional[str]` Other financing activities - `other_investing_activities: Optional[str]` Other investing activities - `other_non_cash_items: Optional[str]` Other non-cash items - `other_working_capital: Optional[str]` Change in other working capital - `preferred_dividends_paid: Optional[str]` Preferred dividends paid - `purchases_of_investments: Optional[str]` Purchases of investments - `sales_maturities_of_investments: Optional[str]` Sales and maturities of investments - `short_term_net_debt_issuance: Optional[str]` Short-term net debt issuance - `stock_based_compensation: Optional[str]` Stock-based compensation expense # Market Data ## Get Snapshots `v1.instrument_data.market_data.get_snapshots(MarketDataGetSnapshotsParams**kwargs) -> MarketDataGetSnapshotsResponse` **get** `/v1/market-data/snapshot` Get market data snapshots for one or more securities. ### Parameters - `instrument_ids: Optional[Sequence[str]]` Comma-separated OEMS instrument UUIDs. ### Returns - `class MarketDataGetSnapshotsResponse: …` - `data: MarketDataSnapshotList` - `instrument_id: str` OEMS instrument identifier. - `symbol: str` Display symbol for the security. - `cumulative_volume: Optional[int]` Cumulative traded volume reported on the most recent trade, in shares for equities or contracts for options. Absent when no trade is available. - `last_quote: Optional[SnapshotQuote]` Most recent quote if available. - `ask: str` Current best ask. - `bid: str` Current best bid. - `midpoint: str` Midpoint of bid and ask. - `ask_size: Optional[int]` Size at the best ask, in shares. - `bid_size: Optional[int]` Size at the best bid, in shares. - `last_trade: Optional[SnapshotLastTrade]` Most recent last-sale trade if available. - `price: str` Most recent last-sale eligible trade price. - `name: Optional[str]` Security name if available. - `session: Optional[SnapshotSession]` Session metrics computed from previous close and last trade, if available. - `change: str` Absolute change from previous close to last trade. - `change_percent: str` Percent change from previous close to last trade. - `previous_close: str` Previous session close price. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.market_data.get_snapshots() print(response) ``` #### Response ```json { "data": [ { "cumulative_volume": 12345678, "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "last_quote": { "ask": "210.14", "ask_size": 120, "bid": "210.10", "bid_size": 100, "midpoint": "210.12" }, "last_trade": { "price": "210.12" }, "name": "Apple Inc.", "session": { "change": "1.82", "change_percent": "0.8737", "previous_close": "208.30" }, "symbol": "AAPL" } ], "error": null, "metadata": { "request_id": "2d0c9159-8f5d-49ca-a861-0d8346fd11da" } } ``` ## Get Daily Aggregate Summaries `v1.instrument_data.market_data.get_daily_summaries(MarketDataGetDailySummariesParams**kwargs) -> MarketDataGetDailySummariesResponse` **get** `/v1/market-data/daily-summary` Returns the most recent OHLV and current price for the requested OEMS instruments. Backed by the in-memory Polygon snapshot cache. Response contract: every request returns one row per **unique** `instrument_id`, in first-seen request order. Unresolvable IDs come back with `symbol = null` and every market-data field `null`; resolvable IDs with no cache entry come back with `symbol` populated but market-data fields `null`. **Note (temporary):** ID resolution currently goes through the supplemental screener (OEMS instrument_id → FMP fmp_symbol → metadata_id → realtime cache). Removed when the market-data service serves daily aggregates directly, or when Polygon symbology is loaded into the instrument cache. ### Parameters - `instrument_ids: str` Comma-separated OEMS instrument UUIDs (required, 1..=100) ### Returns - `class MarketDataGetDailySummariesResponse: …` - `data: DailySummaryList` - `instrument_id: str` OEMS instrument identifier. Always populated; echoes the request ID. - `high: Optional[str]` Session high. - `low: Optional[str]` Session low. - `open: Optional[str]` Opening price for the session. - `symbol: Optional[str]` Display symbol for the security. `None` for unresolvable IDs. - `trade_date: Optional[date]` Session date the OHLV represents, US/Eastern. - `volume: Optional[int]` Session cumulative trading volume. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.market_data.get_daily_summaries( instrument_ids="instrument_ids", ) print(response) ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "high": "215.20", "low": "210.10", "open": "211.00", "symbol": "AAPL", "trade_date": "2026-04-23", "volume": 88000000 } ] } ``` ## Domain Types ### Daily Summary - `class DailySummary: …` Daily aggregate (OHLV) summary for a single instrument. Returned by `GET /market-data/daily-summary`. Every field except `instrument_id` is `Option`: - Unresolvable `instrument_id` → all other fields `None` (including `symbol`). - Resolvable `instrument_id` with no realtime cache entry → `symbol` populated, OHLV/`trade_date` `None`. - `trade_date` reflects the session the OHLV represents (today during trading hours, the last trading date during weekends/holidays). - `instrument_id: str` OEMS instrument identifier. Always populated; echoes the request ID. - `high: Optional[str]` Session high. - `low: Optional[str]` Session low. - `open: Optional[str]` Opening price for the session. - `symbol: Optional[str]` Display symbol for the security. `None` for unresolvable IDs. - `trade_date: Optional[date]` Session date the OHLV represents, US/Eastern. - `volume: Optional[int]` Session cumulative trading volume. ### Daily Summary List - `List[DailySummary]` - `instrument_id: str` OEMS instrument identifier. Always populated; echoes the request ID. - `high: Optional[str]` Session high. - `low: Optional[str]` Session low. - `open: Optional[str]` Opening price for the session. - `symbol: Optional[str]` Display symbol for the security. `None` for unresolvable IDs. - `trade_date: Optional[date]` Session date the OHLV represents, US/Eastern. - `volume: Optional[int]` Session cumulative trading volume. ### Market Data Snapshot - `class MarketDataSnapshot: …` Market data snapshot for a single security. - `instrument_id: str` OEMS instrument identifier. - `symbol: str` Display symbol for the security. - `cumulative_volume: Optional[int]` Cumulative traded volume reported on the most recent trade, in shares for equities or contracts for options. Absent when no trade is available. - `last_quote: Optional[SnapshotQuote]` Most recent quote if available. - `ask: str` Current best ask. - `bid: str` Current best bid. - `midpoint: str` Midpoint of bid and ask. - `ask_size: Optional[int]` Size at the best ask, in shares. - `bid_size: Optional[int]` Size at the best bid, in shares. - `last_trade: Optional[SnapshotLastTrade]` Most recent last-sale trade if available. - `price: str` Most recent last-sale eligible trade price. - `name: Optional[str]` Security name if available. - `session: Optional[SnapshotSession]` Session metrics computed from previous close and last trade, if available. - `change: str` Absolute change from previous close to last trade. - `change_percent: str` Percent change from previous close to last trade. - `previous_close: str` Previous session close price. ### Market Data Snapshot List - `List[MarketDataSnapshot]` - `instrument_id: str` OEMS instrument identifier. - `symbol: str` Display symbol for the security. - `cumulative_volume: Optional[int]` Cumulative traded volume reported on the most recent trade, in shares for equities or contracts for options. Absent when no trade is available. - `last_quote: Optional[SnapshotQuote]` Most recent quote if available. - `ask: str` Current best ask. - `bid: str` Current best bid. - `midpoint: str` Midpoint of bid and ask. - `ask_size: Optional[int]` Size at the best ask, in shares. - `bid_size: Optional[int]` Size at the best bid, in shares. - `last_trade: Optional[SnapshotLastTrade]` Most recent last-sale trade if available. - `price: str` Most recent last-sale eligible trade price. - `name: Optional[str]` Security name if available. - `session: Optional[SnapshotSession]` Session metrics computed from previous close and last trade, if available. - `change: str` Absolute change from previous close to last trade. - `change_percent: str` Percent change from previous close to last trade. - `previous_close: str` Previous session close price. ### Snapshot Last Trade - `class SnapshotLastTrade: …` Last-trade fields for a market data snapshot. - `price: str` Most recent last-sale eligible trade price. ### Snapshot Quote - `class SnapshotQuote: …` L1 quote fields for a market data snapshot. - `ask: str` Current best ask. - `bid: str` Current best bid. - `midpoint: str` Midpoint of bid and ask. - `ask_size: Optional[int]` Size at the best ask, in shares. - `bid_size: Optional[int]` Size at the best bid, in shares. ### Snapshot Session - `class SnapshotSession: …` Session-level pricing metrics for a market data snapshot. - `change: str` Absolute change from previous close to last trade. - `change_percent: str` Percent change from previous close to last trade. - `previous_close: str` Previous session close price. ### Market Data Get Snapshots Response - `class MarketDataGetSnapshotsResponse: …` - `data: MarketDataSnapshotList` - `instrument_id: str` OEMS instrument identifier. - `symbol: str` Display symbol for the security. - `cumulative_volume: Optional[int]` Cumulative traded volume reported on the most recent trade, in shares for equities or contracts for options. Absent when no trade is available. - `last_quote: Optional[SnapshotQuote]` Most recent quote if available. - `ask: str` Current best ask. - `bid: str` Current best bid. - `midpoint: str` Midpoint of bid and ask. - `ask_size: Optional[int]` Size at the best ask, in shares. - `bid_size: Optional[int]` Size at the best bid, in shares. - `last_trade: Optional[SnapshotLastTrade]` Most recent last-sale trade if available. - `price: str` Most recent last-sale eligible trade price. - `name: Optional[str]` Security name if available. - `session: Optional[SnapshotSession]` Session metrics computed from previous close and last trade, if available. - `change: str` Absolute change from previous close to last trade. - `change_percent: str` Percent change from previous close to last trade. - `previous_close: str` Previous session close price. ### Market Data Get Daily Summaries Response - `class MarketDataGetDailySummariesResponse: …` - `data: DailySummaryList` - `instrument_id: str` OEMS instrument identifier. Always populated; echoes the request ID. - `high: Optional[str]` Session high. - `low: Optional[str]` Session low. - `open: Optional[str]` Opening price for the session. - `symbol: Optional[str]` Display symbol for the security. `None` for unresolvable IDs. - `trade_date: Optional[date]` Session date the OHLV represents, US/Eastern. - `volume: Optional[int]` Session cumulative trading volume. # News ## Get News `v1.instrument_data.news.get_news(NewsGetNewsParams**kwargs) -> NewsGetNewsResponse` **get** `/v1/news` Retrieves news items with optional filtering by security IDs, time range, publisher, type, and text query. ### Parameters - `exclude_publishers: Optional[str]` Comma-separated list of publishers to exclude (mutually exclusive with include_publishers). - `from_: Optional[str]` Inclusive start timestamp. Accepts `YYYY-MM-DD` or RFC3339 datetime. - `include_publishers: Optional[str]` Comma-separated list of publishers to include (mutually exclusive with exclude_publishers). - `instrument_ids: Optional[Sequence[str]]` Comma-delimited OEMS instrument UUIDs to filter by. - `news_type: Optional[Literal["NEWS", "PRESS_RELEASE"]]` Filter by news type. - `"NEWS"` - `"PRESS_RELEASE"` - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `search_query: Optional[str]` Free-text query matched against title/text and associated security IDs. - `sectors: Optional[List[Literal["BASIC_MATERIALS", "COMMUNICATION_SERVICES", "CONSUMER_CYCLICAL", 8 more]]]` Comma-separated sector values to filter by. - `"BASIC_MATERIALS"` - `"COMMUNICATION_SERVICES"` - `"CONSUMER_CYCLICAL"` - `"CONSUMER_DEFENSIVE"` - `"ENERGY"` - `"FINANCIAL_SERVICES"` - `"HEALTHCARE"` - `"INDUSTRIALS"` - `"REAL_ESTATE"` - `"TECHNOLOGY"` - `"UTILITIES"` - `to: Optional[str]` Inclusive end timestamp. Accepts `YYYY-MM-DD` or RFC3339 datetime. ### Returns - `class NewsGetNewsResponse: …` - `data: NewsItemList` - `instruments: List[NewsInstrument]` Instruments associated with this news item. - `instrument_id: str` OEMS instrument UUID. - `name: Optional[str]` Instrument name/description, if available from instrument cache enrichment. - `symbol: Optional[str]` Trading symbol, if available from instrument cache enrichment. - `news_type: NewsType` Classification of the item. - `"NEWS"` - `"PRESS_RELEASE"` - `published_at: datetime` The published date/time of the article in UTC. - `publisher: str` The publisher or newswire source. - `title: str` The headline/title of the article. - `url: str` Canonical URL to the full article. - `image_url: Optional[str]` URL of an associated image if provided by the source. - `site: Optional[str]` The primary domain/site of the publisher. - `text: Optional[str]` The full or excerpted article body. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instrument_data.news.get_news() print(response) ``` #### Response ```json { "data": [ { "instruments": [ { "instrument_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Apple Inc.", "symbol": "AAPL" } ], "news_type": "NEWS", "published_at": "2025-10-31T14:30:00.000000000Z", "publisher": "Reuters", "site": "reuters.com", "title": "Apple announces new hardware lineup", "url": "https://example.com/news/1" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3Rfc3ltYm9sPVRTM0E", "page_number": 1, "request_id": "0f1a2b3c-4d5e-6f78-9012-3a4b5c6d7e8f", "total_items": 25, "total_pages": 3 } } ``` ## Domain Types ### News Instrument - `class NewsInstrument: …` Instrument associated with a news item. - `instrument_id: str` OEMS instrument UUID. - `name: Optional[str]` Instrument name/description, if available from instrument cache enrichment. - `symbol: Optional[str]` Trading symbol, if available from instrument cache enrichment. ### News Item - `class NewsItem: …` A single news item and its associated instruments. - `instruments: List[NewsInstrument]` Instruments associated with this news item. - `instrument_id: str` OEMS instrument UUID. - `name: Optional[str]` Instrument name/description, if available from instrument cache enrichment. - `symbol: Optional[str]` Trading symbol, if available from instrument cache enrichment. - `news_type: NewsType` Classification of the item. - `"NEWS"` - `"PRESS_RELEASE"` - `published_at: datetime` The published date/time of the article in UTC. - `publisher: str` The publisher or newswire source. - `title: str` The headline/title of the article. - `url: str` Canonical URL to the full article. - `image_url: Optional[str]` URL of an associated image if provided by the source. - `site: Optional[str]` The primary domain/site of the publisher. - `text: Optional[str]` The full or excerpted article body. ### News Item List - `List[NewsItem]` - `instruments: List[NewsInstrument]` Instruments associated with this news item. - `instrument_id: str` OEMS instrument UUID. - `name: Optional[str]` Instrument name/description, if available from instrument cache enrichment. - `symbol: Optional[str]` Trading symbol, if available from instrument cache enrichment. - `news_type: NewsType` Classification of the item. - `"NEWS"` - `"PRESS_RELEASE"` - `published_at: datetime` The published date/time of the article in UTC. - `publisher: str` The publisher or newswire source. - `title: str` The headline/title of the article. - `url: str` Canonical URL to the full article. - `image_url: Optional[str]` URL of an associated image if provided by the source. - `site: Optional[str]` The primary domain/site of the publisher. - `text: Optional[str]` The full or excerpted article body. ### News Type - `Literal["NEWS", "PRESS_RELEASE"]` News item classification. - `"NEWS"` - `"PRESS_RELEASE"` ### News Get News Response - `class NewsGetNewsResponse: …` - `data: NewsItemList` - `instruments: List[NewsInstrument]` Instruments associated with this news item. - `instrument_id: str` OEMS instrument UUID. - `name: Optional[str]` Instrument name/description, if available from instrument cache enrichment. - `symbol: Optional[str]` Trading symbol, if available from instrument cache enrichment. - `news_type: NewsType` Classification of the item. - `"NEWS"` - `"PRESS_RELEASE"` - `published_at: datetime` The published date/time of the article in UTC. - `publisher: str` The publisher or newswire source. - `title: str` The headline/title of the article. - `url: str` Canonical URL to the full article. - `image_url: Optional[str]` URL of an associated image if provided by the source. - `site: Optional[str]` The primary domain/site of the publisher. - `text: Optional[str]` The full or excerpted article body. # Instruments ## Get Instruments `v1.instruments.get_instruments(InstrumentGetInstrumentsParams**kwargs) -> InstrumentGetInstrumentsResponse` **get** `/v1/instruments` Retrieves a list of tradeable instruments. ### Parameters - `easy_to_borrow: Optional[bool]` Filter by easy to borrow status - `instrument_ids: Optional[Sequence[str]]` Comma-separated OEMS instrument UUIDs - `instrument_type: Optional[Literal["COMMON_STOCK", "PREFERRED_STOCK", "OPTION", 2 more]]` Filter by instrument type. OPTION is not supported on this endpoint; use GET /instruments/options/contracts to list option contracts. If omitted, returns all supported instrument types except options. - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `is_liquidation_only: Optional[bool]` Filter by liquidation only status - `is_marginable: Optional[bool]` Filter by marginable status - `is_restricted: Optional[bool]` Filter by restricted status - `is_short_prohibited: Optional[bool]` Filter by short prohibited status - `is_threshold_security: Optional[bool]` Filter by threshold security status - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class InstrumentGetInstrumentsResponse: …` - `data: InstrumentCoreList` - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instruments.get_instruments() print(response) ``` #### Response ```json { "data": [ { "country_of_issue": "US", "currency": "USD", "easy_to_borrow": true, "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b", "instrument_type": "COMMON_STOCK", "is_liquidation_only": false, "is_marginable": true, "is_restricted": false, "is_short_prohibited": false, "is_threshold_security": false, "is_tradable": true, "name": "Apple Inc.", "symbol": "AAPL", "venue": "XNMS" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3Rfc3ltYm9sPUdNRQ==", "page_number": 1, "request_id": "4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d", "total_items": 10, "total_pages": 5 } } ``` ## Get Instrument By ID `v1.instruments.get_instrument_by_id(InstrumentIDOrSymbolinstrument_id, InstrumentGetInstrumentByIDParams**kwargs) -> InstrumentGetInstrumentByIDResponse` **get** `/v1/instruments/{instrument_id}` Retrieves detailed information for a specific instrument. ### Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID - `include_options_expiry_dates: Optional[bool]` When true, include unique options expiry dates for this instrument ### Returns - `class InstrumentGetInstrumentByIDResponse: …` - `data: Instrument` Represents a tradable financial instrument. - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: Optional[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instruments.get_instrument_by_id( instrument_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response) ``` #### Response ```json { "data": { "country_of_issue": "US", "currency": "USD", "easy_to_borrow": true, "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b", "instrument_type": "COMMON_STOCK", "is_liquidation_only": false, "is_marginable": true, "is_restricted": false, "is_short_prohibited": false, "is_threshold_security": false, "is_tradable": true, "long_margin_rate": "0.25", "name": "Apple Inc.", "short_margin_rate": "0.25", "symbol": "AAPL", "venue": "XNMS" }, "error": null, "metadata": { "request_id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" } } ``` ## Search Instruments `v1.instruments.search_instruments(InstrumentSearchInstrumentsParams**kwargs) -> InstrumentSearchInstrumentsResponse` **get** `/v1/instruments/search` Search instruments by symbol, alternate identifier, or company name. The `q` parameter is case-insensitive and supports ticker symbols, alternate identifiers such as CUSIP, ISIN, OPRA root, and CMS identifiers, and company names for non-option instruments. Results are ranked by match quality plus instrument quality signals including log-scaled ADV, listing status, marginability, easy-to-borrow status, and OTC, restricted, and liquidation-only penalties. Defaults to the `EQUITY` asset class (common stocks, preferred shares, ADRs, ETFs, and exchange-traded mutual funds). Pass `asset_class=OPTION` to search option contracts by symbol or alternate identifier. ### Parameters - `q: str` Search term applied case-insensitively to ticker symbols, alternate identifiers (CUSIP, ISIN, OPRA root, CMS), and company names for non-option instruments. Option searches match symbols and alternate identifiers. - `asset_class: Optional[str]` Comma-separated asset classes (EQUITY|OPTION|WARRANT|BOND|FX|OTHER). Defaults to EQUITY. - `country: Optional[str]` Optional listing-country filter (e.g., US). - `currency: Optional[str]` Optional ISO currency filter (e.g., USD). - `include_inactive: Optional[bool]` Include inactive instruments. Default false. - `include_restricted: Optional[bool]` Include restricted instruments. Default true (penalized in ranking). - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class InstrumentSearchInstrumentsResponse: …` - `data: InstrumentCoreList` - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instruments.search_instruments( q="q", ) print(response) ``` #### Response ```json { "data": [ { "currency": "USD", "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b", "instrument_type": "COMMON_STOCK", "is_marginable": true, "name": "Apple Inc.", "symbol": "AAPL", "venue": "XNMS" } ], "error": null, "metadata": { "request_id": "..." } } ``` ## Get Option Contracts `v1.instruments.get_option_contracts(InstrumentGetOptionContractsParams**kwargs) -> InstrumentGetOptionContractsResponse` **get** `/v1/instruments/options/contracts` List options contracts. Returns options contracts for a given underlier with options-specific metadata. Exactly one underlier identifier must be provided. ### Parameters - `contract_type: Optional[ContractType]` Filter by contract type: CALL or PUT - `"CALL"` - `"PUT"` - `expiry: Optional[Union[null, null]]` Filter to contracts expiring on this date (YYYY-MM-DD) - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `underlier: Optional[str]` Underlier symbol (e.g., AAPL, SPX) - `underlying_instrument_id: Optional[InstrumentIDOrSymbol]` OEMS instrument UUID or symbol of the underlying equity/index ### Returns - `class InstrumentGetOptionContractsResponse: …` - `data: OptionsContractList` - `id: str` OEMS instrument identifier - `contract_type: ContractType` Whether this is a CALL or PUT - `"CALL"` - `"PUT"` - `currency: str` ISO currency code - `exchange: str` MIC code of the primary listing venue - `exercise_style: ExerciseStyle` Exercise style - `"AMERICAN"` - `"EUROPEAN"` - `expiry: date` Expiration date - `is_liquidation_only: bool` Whether the contract is liquidation-only - `is_marginable: bool` Whether the contract is marginable - `is_restricted: bool` Whether the contract is restricted from trading - `listing_type: ListingType` Listing type - `"STANDARD"` - `"FLEX"` - `"OTC"` - `multiplier: str` Contract multiplier (100 for standard options) - `strike_price: str` Strike price - `symbol: str` OSI symbol (e.g. "AAPL 251219C00150000") - `open_interest: Optional[int]` Open interest (number of outstanding contracts), if available - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the underlying instrument, if resolvable ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.instruments.get_option_contracts() print(response) ``` #### Response ```json { "data": [ { "contract_type": "CALL", "currency": "USD", "exchange": "BATO", "exercise_style": "AMERICAN", "expiry": "2026-03-20", "id": "b6f4b5e2-94a8-4fe4-9a85-2b4a81d30cc5", "is_liquidation_only": false, "is_marginable": true, "is_restricted": false, "is_tradable": true, "listing_type": "STANDARD", "multiplier": "100", "strike_price": "180", "symbol": "AAPL 260320C00180000", "underlying_instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8" }, { "contract_type": "PUT", "currency": "USD", "exchange": "BATO", "exercise_style": "AMERICAN", "expiry": "2026-03-20", "id": "c7e5c6f3-a5b9-5gf5-0b96-3c5b92e41dd6", "is_liquidation_only": false, "is_marginable": true, "is_restricted": false, "is_tradable": true, "listing_type": "STANDARD", "multiplier": "100", "strike_price": "180", "symbol": "AAPL 260320P00180000", "underlying_instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8" } ], "metadata": { "page_number": 1, "request_id": "c2d0429d-c629-4ee1-b719-df007157f3bb", "total_items": 2, "total_pages": 1 } } ``` ## Domain Types ### Contract Type - `Literal["CALL", "PUT"]` The type of options contract - `"CALL"` - `"PUT"` ### Exercise Style - `Literal["AMERICAN", "EUROPEAN"]` The exercise style of an options contract - `"AMERICAN"` - `"EUROPEAN"` ### Instrument - `class Instrument: …` Represents a tradable financial instrument. - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: Optional[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Instrument Core - `class InstrumentCore: …` - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Instrument Core List - `List[InstrumentCore]` - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Listing Type - `Literal["STANDARD", "FLEX", "OTC"]` The listing type of an options contract - `"STANDARD"` - `"FLEX"` - `"OTC"` ### Options Contract - `class OptionsContract: …` An options contract with options-specific metadata - `id: str` OEMS instrument identifier - `contract_type: ContractType` Whether this is a CALL or PUT - `"CALL"` - `"PUT"` - `currency: str` ISO currency code - `exchange: str` MIC code of the primary listing venue - `exercise_style: ExerciseStyle` Exercise style - `"AMERICAN"` - `"EUROPEAN"` - `expiry: date` Expiration date - `is_liquidation_only: bool` Whether the contract is liquidation-only - `is_marginable: bool` Whether the contract is marginable - `is_restricted: bool` Whether the contract is restricted from trading - `listing_type: ListingType` Listing type - `"STANDARD"` - `"FLEX"` - `"OTC"` - `multiplier: str` Contract multiplier (100 for standard options) - `strike_price: str` Strike price - `symbol: str` OSI symbol (e.g. "AAPL 251219C00150000") - `open_interest: Optional[int]` Open interest (number of outstanding contracts), if available - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the underlying instrument, if resolvable ### Options Contract List - `List[OptionsContract]` - `id: str` OEMS instrument identifier - `contract_type: ContractType` Whether this is a CALL or PUT - `"CALL"` - `"PUT"` - `currency: str` ISO currency code - `exchange: str` MIC code of the primary listing venue - `exercise_style: ExerciseStyle` Exercise style - `"AMERICAN"` - `"EUROPEAN"` - `expiry: date` Expiration date - `is_liquidation_only: bool` Whether the contract is liquidation-only - `is_marginable: bool` Whether the contract is marginable - `is_restricted: bool` Whether the contract is restricted from trading - `listing_type: ListingType` Listing type - `"STANDARD"` - `"FLEX"` - `"OTC"` - `multiplier: str` Contract multiplier (100 for standard options) - `strike_price: str` Strike price - `symbol: str` OSI symbol (e.g. "AAPL 251219C00150000") - `open_interest: Optional[int]` Open interest (number of outstanding contracts), if available - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the underlying instrument, if resolvable ### Instrument Get Instruments Response - `class InstrumentGetInstrumentsResponse: …` - `data: InstrumentCoreList` - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Instrument Get Instrument By ID Response - `class InstrumentGetInstrumentByIDResponse: …` - `data: Instrument` Represents a tradable financial instrument. - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: Optional[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Instrument Search Instruments Response - `class InstrumentSearchInstrumentsResponse: …` - `data: InstrumentCoreList` - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Instrument Get Option Contracts Response - `class InstrumentGetOptionContractsResponse: …` - `data: OptionsContractList` - `id: str` OEMS instrument identifier - `contract_type: ContractType` Whether this is a CALL or PUT - `"CALL"` - `"PUT"` - `currency: str` ISO currency code - `exchange: str` MIC code of the primary listing venue - `exercise_style: ExerciseStyle` Exercise style - `"AMERICAN"` - `"EUROPEAN"` - `expiry: date` Expiration date - `is_liquidation_only: bool` Whether the contract is liquidation-only - `is_marginable: bool` Whether the contract is marginable - `is_restricted: bool` Whether the contract is restricted from trading - `listing_type: ListingType` Listing type - `"STANDARD"` - `"FLEX"` - `"OTC"` - `multiplier: str` Contract multiplier (100 for standard options) - `strike_price: str` Strike price - `symbol: str` OSI symbol (e.g. "AAPL 251219C00150000") - `open_interest: Optional[int]` Open interest (number of outstanding contracts), if available - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the underlying instrument, if resolvable # Omni AI ## Domain Types ### Action Button - `class ActionButton: …` Button metadata shared by chart and suggested-actions payloads. - `button_id: str` Stable button identifier within the content part. - `label: str` User-visible label. - `prompt: Optional[PromptButtonAction]` Follow-up prompt to submit as the next user message. - `prompt: str` Prompt text to submit as the next user turn. - `structured_action: Optional[StructuredActionButtonAction]` Structured action in the same message to execute on click. - `action_id: Optional[str]` UUID of a `structured_action` content part in the same message. ### Chart Payload - `class ChartPayload: …` Typed chart payload rendered inline in assistant content. - `chart_id: str` Stable chart identifier scoped to the content part. - `action_buttons: Optional[List[ActionButton]]` Buttons associated with this chart. - `button_id: str` Stable button identifier within the content part. - `label: str` User-visible label. - `prompt: Optional[PromptButtonAction]` Follow-up prompt to submit as the next user message. - `prompt: str` Prompt text to submit as the next user turn. - `structured_action: Optional[StructuredActionButtonAction]` Structured action in the same message to execute on click. - `action_id: Optional[str]` UUID of a `structured_action` content part in the same message. - `data_chart: Optional[DataChart]` Explicit series-driven chart definition. - `series: Optional[List[ChartSeries]]` - `name: str` - `points: Optional[List[ChartPoint]]` - `x: str` - `y: float` - `symbol_chart: Optional[SymbolChart]` Symbol-driven chart definition. - `symbol: str` - `timeframe: Optional[str]` ### Chart Point - `class ChartPoint: …` Single chart coordinate. - `x: str` - `y: float` ### Chart Series - `class ChartSeries: …` Named data series within a chart. - `name: str` - `points: Optional[List[ChartPoint]]` - `x: str` - `y: float` ### Content Part Chart Payload - `class ContentPartChartPayload: …` Chart payload content part. - `payload: ChartPayload` Typed chart payload rendered inline in assistant content. - `chart_id: str` Stable chart identifier scoped to the content part. - `action_buttons: Optional[List[ActionButton]]` Buttons associated with this chart. - `button_id: str` Stable button identifier within the content part. - `label: str` User-visible label. - `prompt: Optional[PromptButtonAction]` Follow-up prompt to submit as the next user message. - `prompt: str` Prompt text to submit as the next user turn. - `structured_action: Optional[StructuredActionButtonAction]` Structured action in the same message to execute on click. - `action_id: Optional[str]` UUID of a `structured_action` content part in the same message. - `data_chart: Optional[DataChart]` Explicit series-driven chart definition. - `series: Optional[List[ChartSeries]]` - `name: str` - `points: Optional[List[ChartPoint]]` - `x: str` - `y: float` - `symbol_chart: Optional[SymbolChart]` Symbol-driven chart definition. - `symbol: str` - `timeframe: Optional[str]` ### Content Part Custom Payload - `class ContentPartCustomPayload: …` Escape-hatch custom payload content part. - `payload: object` ### Content Part Structured Action Payload - `class ContentPartStructuredActionPayload: …` Structured action content part. - `action: StructuredAction` Structured actions that Omni AI can return to clients. These actions provide machine-readable instructions for the client to execute, such as prefilling an order ticket, opening a chart, or navigating to a route. - `class PrefillOrder: …` Prefill an order ticket for user confirmation - `prefill_order: PrefillOrderAction` Prefill an order ticket for user confirmation - `class PrefillNewOrderAction: …` Create one or more new orders. - `action_type: Literal["NEW"]` - `"NEW"` - `class PrefillCancelOrderAction: …` Cancel one or more existing orders. - `action_type: Literal["CANCEL"]` - `"CANCEL"` - `class OpenChart: …` Open a chart for a symbol - `open_chart: OpenChartAction` Open a chart for a symbol - `symbol: str` Trading symbol to chart - `extras: Optional[object]` Additional chart configuration (indicators, overlays, etc.) - `timeframe: Optional[str]` Chart timeframe (e.g., "1D", "1W", "1M", "3M", "1Y", "5Y") - `class OpenScreener: …` Open a stock screener with filters - `open_screener: OpenScreenerAction` Open a stock screener with filters - `filters: List[ScreenerFilter]` Filter criteria for the screener - `field: str` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: str` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: object` Filter value - `field_filter: Optional[List[str]]` Optional field/column selection for screener results. - `page_size: Optional[int]` Optional page size. - `sort_by: Optional[str]` Optional sort field for screener rows. - `sort_direction: Optional[str]` Optional sort direction (`ASC` or `DESC`). - `class OpenEntitlementConsent: …` Open entitlement consent flow - `open_entitlement_consent: OpenEntitlementConsentAction` Open entitlement consent flow - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `reason: str` - `requested_entitlement_codes: List[EntitlementCode]` - `"omni.account_data"` - `trading_account_ids: List[int]` - `action_id: str` ### Content Part Suggested Actions Payload - `class ContentPartSuggestedActionsPayload: …` Suggested actions payload content part. - `payload: SuggestedActionsPayload` Suggested follow-up buttons rendered at the end of an assistant message. - `action_buttons: Optional[List[ActionButton]]` Ordered message-level buttons. - `button_id: str` Stable button identifier within the content part. - `label: str` User-visible label. - `prompt: Optional[PromptButtonAction]` Follow-up prompt to submit as the next user message. - `prompt: str` Prompt text to submit as the next user turn. - `structured_action: Optional[StructuredActionButtonAction]` Structured action in the same message to execute on click. - `action_id: Optional[str]` UUID of a `structured_action` content part in the same message. ### Content Part Text Payload - `class ContentPartTextPayload: …` Text content part. - `text: str` ### Content Part Thinking Payload - `class ContentPartThinkingPayload: …` Thinking content part shown on dynamic response polling. - `thoughts: List[str]` ### Data Chart - `class DataChart: …` Chart represented by explicit data series. - `series: Optional[List[ChartSeries]]` - `name: str` - `points: Optional[List[ChartPoint]]` - `x: str` - `y: float` ### Open Chart Action - `class OpenChartAction: …` Action to open a chart for a symbol. - `symbol: str` Trading symbol to chart - `extras: Optional[object]` Additional chart configuration (indicators, overlays, etc.) - `timeframe: Optional[str]` Chart timeframe (e.g., "1D", "1W", "1M", "3M", "1Y", "5Y") ### Open Entitlement Consent Action - `class OpenEntitlementConsentAction: …` Action to open entitlement consent flow for one or more accounts. - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `reason: str` - `requested_entitlement_codes: List[EntitlementCode]` - `"omni.account_data"` - `trading_account_ids: List[int]` ### Open Screener Action - `class OpenScreenerAction: …` Action to open a stock screener with filters. - `filters: List[ScreenerFilter]` Filter criteria for the screener - `field: str` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: str` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: object` Filter value - `field_filter: Optional[List[str]]` Optional field/column selection for screener results. - `page_size: Optional[int]` Optional page size. - `sort_by: Optional[str]` Optional sort field for screener rows. - `sort_direction: Optional[str]` Optional sort direction (`ASC` or `DESC`). ### Prefill Cancel Order Action - `class PrefillCancelOrderAction: …` Cancel-order prefill action. - `orders: List[CancelOrderRequest]` Orders to cancel using the same identifiers required by the cancel-order API. - `account_id: int` Account ID (from path parameter) - `order_id: str` Order ID to cancel (from path parameter) ### Prefill New Order Action - `class PrefillNewOrderAction: …` New-order prefill action. - `orders: List[NewOrderRequest]` Orders to prefill using the same shape accepted by the orders API. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `order_type: RequestOrderType` Type of order - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `quantity: str` Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer) - `side: Side` Side of the order - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `time_in_force: RequestTimeInForce` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `id: Optional[str]` Optional client-provided unique ID (idempotency). Required to be unique per account. - `expires_at: Optional[datetime]` The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Allow trading outside regular trading hours. Some brokers disallow options outside RTH. - `instrument_id: Optional[InstrumentIDOrSymbol]` OEMS instrument UUID - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (required for LIMIT and STOP_LIMIT orders) - `position_effect: Optional[PositionEffect]` Required when instrument_type is OPTION. Specifies whether the order opens or closes a position. - `"OPEN"` - `"CLOSE"` - `stop_price: Optional[str]` Stop price (required for STOP and STOP_LIMIT orders) - `symbol: Optional[str]` Trading symbol. For equities, use the ticker symbol (e.g., "AAPL"). For options, use the OSI symbol (e.g., "AAPL 250117C00190000"). Either `symbol` or `instrument_id` must be provided. - `trailing_offset: Optional[str]` Trailing offset amount (required for trailing orders) - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type (PRICE or PERCENT_BPS) - `"PRICE"` - `"BPS"` ### Prefill Order Action - `Union[PrefillNewOrderAction, PrefillCancelOrderAction]` Action to prefill order details for user confirmation. The user must review and authorize the order before submission to the trading API. This action provides parsed order data that can be used to prefill an order ticket UI or submitted directly via the orders API after user confirmation. - `class PrefillNewOrderAction: …` Create one or more new orders. - `action_type: Literal["NEW"]` - `"NEW"` - `class PrefillCancelOrderAction: …` Cancel one or more existing orders. - `action_type: Literal["CANCEL"]` - `"CANCEL"` ### Prompt Button Action - `class PromptButtonAction: …` Prompt-style button behavior. - `prompt: str` Prompt text to submit as the next user turn. ### Screener Filter - `class ScreenerFilter: …` A single filter criterion for the screener. - `field: str` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: str` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: object` Filter value ### Structured Action - `StructuredAction` Structured actions that Omni AI can return to clients. These actions provide machine-readable instructions for the client to execute, such as prefilling an order ticket, opening a chart, or navigating to a route. - `class PrefillOrder: …` Prefill an order ticket for user confirmation - `prefill_order: PrefillOrderAction` Prefill an order ticket for user confirmation - `class PrefillNewOrderAction: …` Create one or more new orders. - `action_type: Literal["NEW"]` - `"NEW"` - `class PrefillCancelOrderAction: …` Cancel one or more existing orders. - `action_type: Literal["CANCEL"]` - `"CANCEL"` - `class OpenChart: …` Open a chart for a symbol - `open_chart: OpenChartAction` Open a chart for a symbol - `symbol: str` Trading symbol to chart - `extras: Optional[object]` Additional chart configuration (indicators, overlays, etc.) - `timeframe: Optional[str]` Chart timeframe (e.g., "1D", "1W", "1M", "3M", "1Y", "5Y") - `class OpenScreener: …` Open a stock screener with filters - `open_screener: OpenScreenerAction` Open a stock screener with filters - `filters: List[ScreenerFilter]` Filter criteria for the screener - `field: str` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: str` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: object` Filter value - `field_filter: Optional[List[str]]` Optional field/column selection for screener results. - `page_size: Optional[int]` Optional page size. - `sort_by: Optional[str]` Optional sort field for screener rows. - `sort_direction: Optional[str]` Optional sort direction (`ASC` or `DESC`). - `class OpenEntitlementConsent: …` Open entitlement consent flow - `open_entitlement_consent: OpenEntitlementConsentAction` Open entitlement consent flow - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `reason: str` - `requested_entitlement_codes: List[EntitlementCode]` - `"omni.account_data"` - `trading_account_ids: List[int]` ### Structured Action Button Action - `class StructuredActionButtonAction: …` Structured-action button behavior. - `action_id: Optional[str]` UUID of a `structured_action` content part in the same message. ### Suggested Actions Payload - `class SuggestedActionsPayload: …` Suggested follow-up buttons rendered at the end of an assistant message. - `action_buttons: Optional[List[ActionButton]]` Ordered message-level buttons. - `button_id: str` Stable button identifier within the content part. - `label: str` User-visible label. - `prompt: Optional[PromptButtonAction]` Follow-up prompt to submit as the next user message. - `prompt: str` Prompt text to submit as the next user turn. - `structured_action: Optional[StructuredActionButtonAction]` Structured action in the same message to execute on click. - `action_id: Optional[str]` UUID of a `structured_action` content part in the same message. ### Symbol Chart - `class SymbolChart: …` Chart for a single symbol and timeframe. - `symbol: str` - `timeframe: Optional[str]` # Entitlements ## Get Entitlements `v1.omni_ai.entitlements.get_entitlements(EntitlementGetEntitlementsParams**kwargs) -> EntitlementGetEntitlementsResponse` **get** `/v1/omni-ai/entitlements` List caller's active entitlement grants. ### Parameters - `trading_account_id: Optional[int]` ### Returns - `class EntitlementGetEntitlementsResponse: …` - `data: EntitlementResourceList` - `agreement_id: str` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: str` - `granted_at: str` - `trading_account_id: int` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.entitlements.get_entitlements() print(response) ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "agreement_id": "agreement_id", "entitlement_code": "omni.account_data", "entitlement_id": "entitlement_id", "granted_at": "granted_at", "trading_account_id": 0 } ] } ``` ## Create Entitlements `v1.omni_ai.entitlements.create_entitlements(EntitlementCreateEntitlementsParams**kwargs) -> EntitlementCreateEntitlementsResponse` **post** `/v1/omni-ai/entitlements` Record consent and upsert one-or-more active grants. ### Parameters - `agreement_id: str` - `requested_entitlement_codes: List[EntitlementCode]` - `"omni.account_data"` - `trading_account_ids: Iterable[int]` ### Returns - `class EntitlementCreateEntitlementsResponse: …` - `data: EntitlementResourceList` - `agreement_id: str` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: str` - `granted_at: str` - `trading_account_id: int` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.entitlements.create_entitlements( agreement_id="01JZ0000000000000000000000", requested_entitlement_codes=["omni.account_data"], trading_account_ids=[100019, 100021], ) print(response) ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "agreement_id": "agreement_id", "entitlement_code": "omni.account_data", "entitlement_id": "entitlement_id", "granted_at": "granted_at", "trading_account_id": 0 } ] } ``` ## Delete Entitlement `v1.omni_ai.entitlements.delete_entitlement(strentitlement_id) -> EntitlementDeleteEntitlementResponse` **delete** `/v1/omni-ai/entitlements/{entitlement_id}` Revoke one entitlement grant by id. ### Parameters - `entitlement_id: str` ### Returns - `class EntitlementDeleteEntitlementResponse: …` - `data: DeleteEntitlementResponse` - `entitlement_id: str` - `revoked: bool` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.entitlements.delete_entitlement( "entitlement_id", ) print(response) ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": { "entitlement_id": "entitlement_id", "revoked": true } } ``` ## Get Entitlement Agreements `v1.omni_ai.entitlements.get_entitlement_agreements() -> EntitlementGetEntitlementAgreementsResponse` **get** `/v1/omni-ai/entitlement-agreements` List current signable entitlement agreements for consent UX. ### Returns - `class EntitlementGetEntitlementAgreementsResponse: …` - `data: EntitlementAgreementResourceList` - `agreement_id: str` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: str` - `document_sha256: str` - `entitlement_codes: List[EntitlementCode]` - `"omni.account_data"` - `title: str` - `version: int` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.entitlements.get_entitlement_agreements() print(response) ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "agreement_id": "agreement_id", "agreement_key": "omni_account_data_access", "document_content": "document_content", "document_sha256": "document_sha256", "entitlement_codes": [ "omni.account_data" ], "title": "title", "version": 0 } ] } ``` ## Domain Types ### Delete Entitlement Response - `class DeleteEntitlementResponse: …` - `entitlement_id: str` - `revoked: bool` ### Entitlement Agreement Key - `Literal["omni_account_data_access"]` Stable entitlement agreement family key. - `"omni_account_data_access"` ### Entitlement Agreement Resource - `class EntitlementAgreementResource: …` - `agreement_id: str` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: str` - `document_sha256: str` - `entitlement_codes: List[EntitlementCode]` - `"omni.account_data"` - `title: str` - `version: int` ### Entitlement Agreement Resource List - `List[EntitlementAgreementResource]` - `agreement_id: str` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: str` - `document_sha256: str` - `entitlement_codes: List[EntitlementCode]` - `"omni.account_data"` - `title: str` - `version: int` ### Entitlement Code - `Literal["omni.account_data"]` Stable entitlement code granted by an agreement. - `"omni.account_data"` ### Entitlement Resource - `class EntitlementResource: …` - `agreement_id: str` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: str` - `granted_at: str` - `trading_account_id: int` ### Entitlement Resource List - `List[EntitlementResource]` - `agreement_id: str` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: str` - `granted_at: str` - `trading_account_id: int` ### Entitlement Get Entitlements Response - `class EntitlementGetEntitlementsResponse: …` - `data: EntitlementResourceList` - `agreement_id: str` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: str` - `granted_at: str` - `trading_account_id: int` ### Entitlement Create Entitlements Response - `class EntitlementCreateEntitlementsResponse: …` - `data: EntitlementResourceList` - `agreement_id: str` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: str` - `granted_at: str` - `trading_account_id: int` ### Entitlement Delete Entitlement Response - `class EntitlementDeleteEntitlementResponse: …` - `data: DeleteEntitlementResponse` - `entitlement_id: str` - `revoked: bool` ### Entitlement Get Entitlement Agreements Response - `class EntitlementGetEntitlementAgreementsResponse: …` - `data: EntitlementAgreementResourceList` - `agreement_id: str` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: str` - `document_sha256: str` - `entitlement_codes: List[EntitlementCode]` - `"omni.account_data"` - `title: str` - `version: int` # Messages ## Get Message By ID `v1.omni_ai.messages.get_message_by_id(strmessage_id, MessageGetMessageByIDParams**kwargs) -> MessageGetMessageByIDResponse` **get** `/v1/omni-ai/messages/{message_id}` Get a finalized message by ID. Returns a single finalized message. Returns **404** if the message belongs to an in-progress assistant turn (use the response endpoint for live output). Once the turn completes, the message becomes available here. ### Parameters - `message_id: str` - `account_id: int` Account ID for the request ### Returns - `class MessageGetMessageByIDResponse: …` - `data: Message` Final immutable message. - `id: str` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: List[MessageContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember2: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember3: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember4: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `created_at: str` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: int` - `thread_id: str` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.messages.get_message_by_id( message_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=0, ) print(response) ``` #### Response ```json { "data": { "content": { "parts": [ { "text": "**Pre-market as of 7:30 AM ET**\n\n ...", "type": "text" }, { "payload": { "actionButtons": [ { "buttonId": "btn_followup_0", "label": "Check my positions", "prompt": { "prompt": "What are my current positions?" } } ] }, "type": "suggested_actions" } ] }, "created_at": "2026-04-16T09:20:17.309212+00:00", "id": "019d9597-599c-7132-a7de-e5c21eaaab77", "outcome": "completed", "role": "ASSISTANT", "seq": 2, "thread_id": "019d9597-597c-7571-a0c9-a49c0e51f6eb" }, "metadata": { "request_id": "0f991501-757d-4051-bf00-6d7f452d6fcf" } } ``` ## Submit Feedback `v1.omni_ai.messages.submit_feedback(strmessage_id, MessageSubmitFeedbackParams**kwargs) -> MessageSubmitFeedbackResponse` **post** `/v1/omni-ai/messages/{message_id}/feedback` Submit feedback on a finalized assistant message. Attaches a score and optional comment to a finalized assistant message. Feedback is only valid for messages with role `ASSISTANT` that have reached a terminal outcome. ### Parameters - `message_id: str` - `account_id: int` Account ID for the request - `score: int` Feedback score (-1, 0, +1 or 1-5) - `comment: Optional[str]` Optional feedback comment - `metadata: Optional[object]` Optional metadata ### Returns - `class MessageSubmitFeedbackResponse: …` - `data: CreateFeedbackResponse` - `created_at: str` - `feedback_id: Optional[str]` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.messages.submit_feedback( message_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=0, score=0, ) print(response) ``` #### Response ```json { "data": { "created_at": "2026-04-23T16:09:51.746912+00:00", "feedback_id": "019dbb1a-d782-7f42-8dd8-a1a7ca5d48e3" }, "metadata": { "request_id": "372a359a-fd4f-4c69-8f11-d80831aa5f23" } } ``` ## Domain Types ### Create Feedback Response - `class CreateFeedbackResponse: …` - `created_at: str` - `feedback_id: Optional[str]` ### Message Get Message By ID Response - `class MessageGetMessageByIDResponse: …` - `data: Message` Final immutable message. - `id: str` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: List[MessageContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember2: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember3: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember4: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `created_at: str` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: int` - `thread_id: str` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` ### Message Submit Feedback Response - `class MessageSubmitFeedbackResponse: …` - `data: CreateFeedbackResponse` - `created_at: str` - `feedback_id: Optional[str]` # Responses ## Get Response By ID `v1.omni_ai.responses.get_response_by_id(strresponse_id, ResponseGetResponseByIDParams**kwargs) -> ResponseGetResponseByIDResponse` **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`. ### Parameters - `response_id: str` - `account_id: int` Account ID for the request ### Returns - `class ResponseGetResponseByIDResponse: …` - `data: Response` Dynamic pollable response. - `id: str` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: str` - `user_message_id: str` - `content: Optional[ResponseContent]` Dynamic response content container. May include thinking parts. - `parts: List[ResponseContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Thinking content part shown on dynamic response polling. - `type: Literal["thinking"]` - `"thinking"` - `class UnionMember2: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember3: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember4: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember5: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` - `output_message_id: Optional[str]` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.responses.get_response_by_id( response_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=0, ) print(response) ``` #### Response ```json { "data": { "content": { "parts": [ { "text": "AAPL 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" } } ``` ## Cancel Response `v1.omni_ai.responses.cancel_response(strresponse_id, ResponseCancelResponseParams**kwargs) -> ResponseCancelResponseResponse` **delete** `/v1/omni-ai/responses/{response_id}` Cancel a response. Requests cancellation of a queued or running response. If the response has already reached a terminal status, this is an idempotent success. A canceled turn still produces a final assistant message with outcome `canceled` in the thread history. ### Parameters - `response_id: str` - `account_id: int` Account ID for the request ### Returns - `class ResponseCancelResponseResponse: …` - `data: CancelResponsePayload` - `canceled: bool` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.responses.cancel_response( response_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=0, ) print(response) ``` #### Response ```json { "data": { "canceled": false }, "metadata": { "request_id": "fa26a786-f5d3-48b0-80eb-778e17af4964" } } ``` ## Domain Types ### Cancel Response Payload - `class CancelResponsePayload: …` - `canceled: bool` ### Error Status - `class ErrorStatus: …` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` ### Response - `class Response: …` Dynamic pollable response. - `id: str` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: str` - `user_message_id: str` - `content: Optional[ResponseContent]` Dynamic response content container. May include thinking parts. - `parts: List[ResponseContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Thinking content part shown on dynamic response polling. - `type: Literal["thinking"]` - `"thinking"` - `class UnionMember2: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember3: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember4: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember5: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` - `output_message_id: Optional[str]` ### Response Content - `class ResponseContent: …` Dynamic response content container. May include thinking parts. - `parts: List[ResponseContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Thinking content part shown on dynamic response polling. - `type: Literal["thinking"]` - `"thinking"` - `class UnionMember2: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember3: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember4: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember5: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` ### Response Content Part - `Union[UnionMember0, UnionMember1, UnionMember2, 3 more]` Dynamic content part visible on a pollable response. - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Thinking content part shown on dynamic response polling. - `type: Literal["thinking"]` - `"thinking"` - `class UnionMember2: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember3: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember4: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember5: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` ### Response Status - `Literal["queued", "running", "succeeded", 2 more]` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` ### Response Get Response By ID Response - `class ResponseGetResponseByIDResponse: …` - `data: Response` Dynamic pollable response. - `id: str` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: str` - `user_message_id: str` - `content: Optional[ResponseContent]` Dynamic response content container. May include thinking parts. - `parts: List[ResponseContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Thinking content part shown on dynamic response polling. - `type: Literal["thinking"]` - `"thinking"` - `class UnionMember2: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember3: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember4: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember5: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` - `output_message_id: Optional[str]` ### Response Cancel Response Response - `class ResponseCancelResponseResponse: …` - `data: CancelResponsePayload` - `canceled: bool` # Threads ## Get Threads `v1.omni_ai.threads.get_threads(ThreadGetThreadsParams**kwargs) -> ThreadGetThreadsResponse` **get** `/v1/omni-ai/threads` List conversation threads. Returns thread metadata ordered by most recently created first. Use `page_size` and `page_token` for pagination. Thread objects contain only metadata (title, timestamps) — use the messages endpoint for conversation history. ### Parameters - `account_id: int` Account ID for the request - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class ThreadGetThreadsResponse: …` - `data: ThreadList` - `id: str` - `created_at: str` - `title: str` - `updated_at: str` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.threads.get_threads( account_id=0, ) print(response) ``` #### Response ```json { "data": [ { "created_at": "2026-04-23T15:15:54.929830+00:00", "id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "title": "What is current price of AAPL?", "updated_at": "2026-04-23T15:15:54.929830+00:00" } ], "metadata": { "request_id": "eb95e1b8-d245-41b1-bbd0-cc1073e68bfd" } } ``` ## Get Thread By ID `v1.omni_ai.threads.get_thread_by_id(strthread_id, ThreadGetThreadByIDParams**kwargs) -> ThreadGetThreadByIDResponse` **get** `/v1/omni-ai/threads/{thread_id}` Get a specific thread. Returns metadata (title, timestamps) for a single thread. Does not include messages — use `GET /omni-ai/threads/{thread_id}/messages` for conversation history. ### Parameters - `thread_id: str` - `account_id: int` Account ID for the request ### Returns - `class ThreadGetThreadByIDResponse: …` - `data: Thread` Thread metadata returned by list/get thread endpoints. - `id: str` - `created_at: str` - `title: str` - `updated_at: str` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.threads.get_thread_by_id( thread_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=0, ) print(response) ``` #### Response ```json { "data": { "created_at": "2026-04-23T15:15:54.929830+00:00", "id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "title": "What is current price of AAPL?", "updated_at": "2026-04-23T15:15:54.929830+00:00" }, "metadata": { "request_id": "5683a394-6dd1-4843-8591-f102ced2e636" } } ``` ## Create Thread `v1.omni_ai.threads.create_thread(ThreadCreateThreadParams**kwargs) -> ThreadCreateThreadResponse` **post** `/v1/omni-ai/threads` Create a new conversation thread. Atomically creates a new thread and submits the first user turn. The response contains a `response_id` that should be polled via `GET /omni-ai/responses/{response_id}` for assistant output. Two creation modes are supported: - **instant** — provide `text` with a natural-language prompt. - **deep\_insights** — provide a `target` ticker and optional `thesis` for long-form research. ### Parameters - `account_id: int` - `type: Literal["instant", "deep_insights"]` Thread creation mode. - `"instant"` - `"deep_insights"` - `capabilities: Optional[List[Literal["PREFILL_ORDER", "OPEN_CHART", "OPEN_SCREENER", "OPEN_ENTITLEMENT_CONSENT"]]]` - `"PREFILL_ORDER"` - `"OPEN_CHART"` - `"OPEN_SCREENER"` - `"OPEN_ENTITLEMENT_CONSENT"` - `target: Optional[Target]` Deep-insights target payload. - `ticker: str` - `type: Literal["ticker"]` Deep-insights target type. Launch supports ticker-only. - `"ticker"` - `text: Optional[str]` - `thesis: Optional[str]` ### Returns - `class ThreadCreateThreadResponse: …` - `data: CreateThreadResponse` Response payload for thread creation. - `response_id: str` - `thread_id: str` - `user_message_id: str` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.threads.create_thread( account_id=19816, type="instant", ) print(response) ``` #### Response ```json { "data": { "response_id": "019dbae9-73b4-7760-a947-8b4bcab57c49", "thread_id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "user_message_id": "019dbae9-73b8-75b2-9c06-ac348927696d" }, "metadata": { "request_id": "f7a9ad4d-753a-403e-aa0e-ca151f991a81" } } ``` ## Get Thread Response `v1.omni_ai.threads.get_thread_response(strthread_id, ThreadGetThreadResponseParams**kwargs) -> ThreadGetThreadResponseResponse` **get** `/v1/omni-ai/threads/{thread_id}/response` Get the active response for a thread. Convenience endpoint to look up the currently active response for a thread without knowing the `response_id`. Useful when reloading a thread whose last finalized message is a `USER` message — this indicates an assistant turn is likely in progress. Returns **404** if no active response exists (the thread is idle). ### Parameters - `thread_id: str` - `account_id: int` Account ID for the request ### Returns - `class ThreadGetThreadResponseResponse: …` - `data: Response` Dynamic pollable response. - `id: str` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: str` - `user_message_id: str` - `content: Optional[ResponseContent]` Dynamic response content container. May include thinking parts. - `parts: List[ResponseContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Thinking content part shown on dynamic response polling. - `type: Literal["thinking"]` - `"thinking"` - `class UnionMember2: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember3: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember4: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember5: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` - `output_message_id: Optional[str]` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.threads.get_thread_response( thread_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=0, ) print(response) ``` #### Response ```json { "data": { "content": { "parts": [ { "text": "", "type": "text" }, { "thoughts": [ "[1/4] Running parallel analysis on AAPL -- fundamentals, technicals, sentiment, and macro..." ], "type": "thinking" } ] }, "id": "019dbb03-cf23-74e1-9c31-ef0136ff7fed", "output_message_id": "019dbb03-cf32-74d1-906b-a148d4be3da9", "status": "running", "thread_id": "019dbb03-cf22-7da0-a663-f51c756efa07", "user_message_id": "019dbb03-cf24-7b03-8286-5bfc2411b052" }, "metadata": { "request_id": "927a85a6-b11b-4cc5-a2cd-3f46ae64e85d" } } ``` ## Get Messages `v1.omni_ai.threads.get_messages(strthread_id, ThreadGetMessagesParams**kwargs) -> ThreadGetMessagesResponse` **get** `/v1/omni-ai/threads/{thread_id}/messages` List finalized messages in a thread. Returns **finalized** messages in chronological order. Messages from in-progress assistant turns are excluded — use `GET /omni-ai/threads/{thread_id}/response` or `GET /omni-ai/responses/{response_id}` for live output. If the last finalized message has role `USER`, an active response likely exists and should be polled separately. ### Parameters - `thread_id: str` - `account_id: int` Account ID for the request - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class ThreadGetMessagesResponse: …` - `data: MessageList` - `id: str` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: List[MessageContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember2: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember3: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember4: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `created_at: str` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: int` - `thread_id: str` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.threads.get_messages( thread_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=0, ) print(response) ``` #### Response ```json { "data": [ { "content": { "parts": [ { "text": "How are the markets doing today?", "type": "text" } ] }, "created_at": "2026-04-16T09:20:17.274943+00:00", "id": "019d9597-5983-7691-8281-7ce264127740", "outcome": "completed", "role": "USER", "seq": 1, "thread_id": "019d9597-597c-7571-a0c9-a49c0e51f6eb" }, { "content": { "parts": [ { "text": "**Pre-market as of 7:30 AM ET**\n\n ...", "type": "text" }, { "payload": { "actionButtons": [ { "buttonId": "btn_followup_0", "label": "Check my positions", "prompt": { "prompt": "What are my current positions?" } } ] }, "type": "suggested_actions" } ] }, "created_at": "2026-04-16T09:20:17.309212+00:00", "id": "019d9597-599c-7132-a7de-e5c21eaaab77", "outcome": "completed", "role": "ASSISTANT", "seq": 2, "thread_id": "019d9597-597c-7571-a0c9-a49c0e51f6eb" } ], "metadata": { "request_id": "664c0f85-cdab-4fac-afe3-8ecc0148cd4a" } } ``` ## Create Message `v1.omni_ai.threads.create_message(strthread_id, ThreadCreateMessageParams**kwargs) -> ThreadCreateMessageResponse` **post** `/v1/omni-ai/threads/{thread_id}/messages` Continue an existing conversation thread. Appends a new user message to the thread and starts an assistant response. Only one response may be active per thread at a time — if the previous turn is still in progress, this endpoint returns **409 Conflict**. Wait for the active response to reach a terminal status before submitting the next turn. Poll the returned `response_id` via `GET /omni-ai/responses/{response_id}` for assistant output. ### Parameters - `thread_id: str` - `account_id: int` - `text: str` - `capabilities: Optional[List[Literal["PREFILL_ORDER", "OPEN_CHART", "OPEN_SCREENER", "OPEN_ENTITLEMENT_CONSENT"]]]` - `"PREFILL_ORDER"` - `"OPEN_CHART"` - `"OPEN_SCREENER"` - `"OPEN_ENTITLEMENT_CONSENT"` ### Returns - `class ThreadCreateMessageResponse: …` - `data: CreateMessageResponse` Response payload for continuing a thread with a new message. - `response_id: str` - `thread_id: str` - `user_message_id: str` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.omni_ai.threads.create_message( thread_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=19816, text="Compare that to AMD.", ) print(response) ``` #### Response ```json { "data": { "response_id": "019dbaec-8dd3-7fa3-89d0-5303609f125f", "thread_id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "user_message_id": "019dbaec-8dd4-7f91-bce2-3ec8fba79eb7" }, "metadata": { "request_id": "48775400-61f4-4c6c-bc6d-8f4996c571c7" } } ``` ## Domain Types ### Create Message Response - `class CreateMessageResponse: …` Response payload for continuing a thread with a new message. - `response_id: str` - `thread_id: str` - `user_message_id: str` ### Create Thread Response - `class CreateThreadResponse: …` Response payload for thread creation. - `response_id: str` - `thread_id: str` - `user_message_id: str` ### Message - `class Message: …` Final immutable message. - `id: str` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: List[MessageContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember2: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember3: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember4: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `created_at: str` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: int` - `thread_id: str` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` ### Message Content - `class MessageContent: …` Finalized immutable message content container. Never includes thinking parts. - `parts: List[MessageContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember2: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember3: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember4: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` ### Message Content Part - `Union[UnionMember0, UnionMember1, UnionMember2, 2 more]` Final immutable content part visible on persisted messages. - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember2: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember3: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember4: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` ### Message List - `List[Message]` - `id: str` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: List[MessageContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember2: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember3: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember4: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `created_at: str` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: int` - `thread_id: str` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` ### Message Outcome - `Literal["completed", "errored", "canceled"]` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` ### Message Role - `Literal["USER", "ASSISTANT"]` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` ### Thread - `class Thread: …` Thread metadata returned by list/get thread endpoints. - `id: str` - `created_at: str` - `title: str` - `updated_at: str` ### Thread List - `List[Thread]` - `id: str` - `created_at: str` - `title: str` - `updated_at: str` ### Thread Get Threads Response - `class ThreadGetThreadsResponse: …` - `data: ThreadList` - `id: str` - `created_at: str` - `title: str` - `updated_at: str` ### Thread Get Thread By ID Response - `class ThreadGetThreadByIDResponse: …` - `data: Thread` Thread metadata returned by list/get thread endpoints. - `id: str` - `created_at: str` - `title: str` - `updated_at: str` ### Thread Create Thread Response - `class ThreadCreateThreadResponse: …` - `data: CreateThreadResponse` Response payload for thread creation. - `response_id: str` - `thread_id: str` - `user_message_id: str` ### Thread Get Thread Response Response - `class ThreadGetThreadResponseResponse: …` - `data: Response` Dynamic pollable response. - `id: str` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: str` - `user_message_id: str` - `content: Optional[ResponseContent]` Dynamic response content container. May include thinking parts. - `parts: List[ResponseContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Thinking content part shown on dynamic response polling. - `type: Literal["thinking"]` - `"thinking"` - `class UnionMember2: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember3: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember4: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember5: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` - `output_message_id: Optional[str]` ### Thread Get Messages Response - `class ThreadGetMessagesResponse: …` - `data: MessageList` - `id: str` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: List[MessageContentPart]` - `class UnionMember0: …` Text content part. - `type: Literal["text"]` - `"text"` - `class UnionMember1: …` Structured action content part. - `type: Literal["structured_action"]` - `"structured_action"` - `class UnionMember2: …` Chart payload content part. - `type: Literal["chart"]` - `"chart"` - `class UnionMember3: …` Suggested actions payload content part. - `type: Literal["suggested_actions"]` - `"suggested_actions"` - `class UnionMember4: …` Escape-hatch custom payload content part. - `type: Literal["custom"]` - `"custom"` - `created_at: str` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: int` - `thread_id: str` - `error: Optional[ErrorStatus]` Shared sanitized error payload. - `code: str` - `message: str` - `details: Optional[object]` ### Thread Create Message Response - `class ThreadCreateMessageResponse: …` - `data: CreateMessageResponse` Response payload for continuing a thread with a new message. - `response_id: str` - `thread_id: str` - `user_message_id: str` # Orders ## Get Orders `v1.orders.get_orders(intaccount_id, OrderGetOrdersParams**kwargs) -> OrderGetOrdersResponse` **get** `/v1/accounts/{account_id}/orders` List orders for an account with optional filtering ### Parameters - `account_id: int` - `from_: Optional[Union[str, datetime]]` The start date and time for the query range, inclusive (ISO 8601 format) - `instrument_ids: Optional[Sequence[str]]` Comma-separated OEMS instrument UUIDs - `instrument_type: Optional[Literal["COMMON_STOCK", "PREFERRED_STOCK", "OPTION", 2 more]]` Instrument type filter (e.g., COMMON_STOCK, OPTION) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `status: Optional[List[Literal["PENDING_NEW", "NEW", "PARTIALLY_FILLED", 12 more]]]` Comma-separated order statuses to filter by - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: Optional[str]` Filter by symbol - `to: Optional[Union[str, datetime]]` The end date and time for the query range, inclusive (ISO 8601 format) - `underlying_instrument_ids: Optional[str]` Comma-separated OEMS instrument UUIDs. Matches options orders whose resolved underlier is any of the given IDs. ### Returns - `class OrderGetOrdersResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.orders.get_orders( account_id=0, ) print(response) ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": "149.95", "client_order_id": "my-ref-id-20251001-001", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "0195f6c7-4f64-7e3c-8b0a-1d8e4f5e6a7b", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.00", "order_type": "LIMIT", "quantity": "100", "side": "BUY", "status": "PARTIALLY_FILLED", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T13:35:10.000000000Z" }, { "account_id": 19816, "average_fill_price": "450.75", "client_order_id": "my-ref-id-20251001-002", "created_at": "2025-10-31T14:00:00.000000000Z", "filled_quantity": "200", "id": "0195f6c8-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "instrument_id": "b2b3b4b5-c2c3-d2d3-e2e3-e4e5e6e7e8e9", "instrument_type": "COMMON_STOCK", "leaves_quantity": "0", "limit_price": null, "order_type": "MARKET", "quantity": "200", "side": "SELL", "status": "FILLED", "stop_price": null, "symbol": "MSFT", "time_in_force": "DAY", "updated_at": "2025-10-31T14:00:05.000000000Z" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3RfaWQ9b3JkXzRjRDVlNkY3ZzhIOWkwSjE=", "page_number": 1, "request_id": "d9a4f5b6-c3d4-6e5f-0a1b-7c8d9e0f1a2b", "total_items": 25, "total_pages": 3 } } ``` ## Get Order By ID `v1.orders.get_order_by_id(strorder_id, OrderGetOrderByIDParams**kwargs) -> OrderGetOrderByIDResponse` **get** `/v1/accounts/{account_id}/orders/{order_id}` Get Order By ID ### Parameters - `account_id: int` - `order_id: str` ### Returns - `class OrderGetOrderByIDResponse: …` - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.orders.get_order_by_id( order_id="order_id", account_id=0, ) print(response) ``` #### Response ```json { "data": { "account_id": 19816, "average_fill_price": "149.95", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "my-ref-id-20251001-001", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.00", "order_type": "LIMIT", "quantity": "100", "side": "BUY", "status": "PARTIALLY_FILLED", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T13:35:10.000000000Z" }, "error": null, "metadata": { "request_id": "0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } ``` ## Submit Orders `v1.orders.submit_orders(intaccount_id, OrderSubmitOrdersParams**kwargs) -> OrderSubmitOrdersResponse` **post** `/v1/accounts/{account_id}/orders` Submit new orders ### Parameters - `account_id: int` - `orders: Iterable[Order]` - `class OrderNewOrderMultilegRequest: …` Multileg strategy order request - `legs: Iterable[OrderNewOrderMultilegRequestLeg]` Legs that compose the strategy. - `instrument_type: SecurityType` Security type for the leg. - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `ratio: str` Ratio for the leg. - `security: str` Trading symbol (e.g. "AAPL" or OSI symbol for options) - `side: Side` Leg side. - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `id: Optional[str]` Optional leg reference identifier. - `position_effect: Optional[PositionEffect]` Optional leg position effect. - `"OPEN"` - `"CLOSE"` - `order_type: RequestOrderType` Type of order (currently MARKET or LIMIT for multileg strategy submission) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `time_in_force: RequestTimeInForce` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `id: Optional[str]` Optional client-provided unique ID (idempotency). Required to be unique per account. - `limit_price: Optional[str]` Strategy price, required for LIMIT orders. - `quantity: Optional[str]` Optional strategy-level quantity. Multiplies leg quantities. Defaults to 1. - `class NewOrderRequest: …` Request to submit a new order (PlaceOrderRequest from spec) - `instrument_type: SecurityType` Type of security - `order_type: RequestOrderType` Type of order - `quantity: str` Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer) - `side: Side` Side of the order - `time_in_force: RequestTimeInForce` Time in force - `id: Optional[str]` Optional client-provided unique ID (idempotency). Required to be unique per account. - `expires_at: Optional[datetime]` The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Allow trading outside regular trading hours. Some brokers disallow options outside RTH. - `instrument_id: Optional[InstrumentIDOrSymbol]` OEMS instrument UUID - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (required for LIMIT and STOP_LIMIT orders) - `position_effect: Optional[PositionEffect]` Required when instrument_type is OPTION. Specifies whether the order opens or closes a position. - `stop_price: Optional[str]` Stop price (required for STOP and STOP_LIMIT orders) - `symbol: Optional[str]` Trading symbol. For equities, use the ticker symbol (e.g., "AAPL"). For options, use the OSI symbol (e.g., "AAPL 250117C00190000"). Either `symbol` or `instrument_id` must be provided. - `trailing_offset: Optional[str]` Trailing offset amount (required for trailing orders) - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type (PRICE or PERCENT_BPS) - `"PRICE"` - `"BPS"` ### Returns - `class OrderSubmitOrdersResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.orders.submit_orders( account_id=0, orders=[{ "legs": [{ "instrument_type": "OPTION", "ratio": "ratio", "security": "0193bb84-447a-706f-996f-097254663f02", "side": "BUY", }, { "instrument_type": "OPTION", "ratio": "ratio", "security": "0193bb84-4db4-78ec-b4fd-cba8be61cf8a", "side": "SELL", }, { "instrument_type": "OPTION", "ratio": "ratio", "security": "0193bb84-5264-7f20-8fd3-35df82cd6ef0", "side": "BUY", }], "order_type": "LIMIT", "time_in_force": "DAY", }], ) print(response) ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": null, "client_order_id": "my-ref-id-20251003-001", "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01", "instrument_id": "c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa", "instrument_type": "COMMON_STOCK", "leaves_quantity": "25", "limit_price": null, "order_type": "MARKET", "quantity": "25", "side": "SELL", "status": "PENDING_NEW", "stop_price": null, "symbol": "GOOG", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNAS" }, { "account_id": 19816, "average_fill_price": null, "client_order_id": "my-ref-id-20251003-002", "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "instrument_id": "d4d5d6d7-e4e5-f4f5-a4a5-a6a7a8a9aaab", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "180.00", "order_type": "LIMIT", "quantity": "50", "side": "BUY", "status": "PENDING_NEW", "stop_price": null, "symbol": "TSLA", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNAS" } ], "error": null, "metadata": { "request_id": "ea0b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d" } } ``` ## Replace Order `v1.orders.replace_order(strorder_id, OrderReplaceOrderParams**kwargs) -> OrderReplaceOrderResponse` **patch** `/v1/accounts/{account_id}/orders/{order_id}` Replace an order with new parameters ### Parameters - `account_id: int` - `order_id: str` - `limit_price: Optional[str]` New limit price for the order - `quantity: Optional[str]` New quantity for the order - `stop_price: Optional[str]` New stop price for the order - `time_in_force: Optional[RequestTimeInForce]` New time in force for the order - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` ### Returns - `class OrderReplaceOrderResponse: …` - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.orders.replace_order( order_id="order_id", account_id=0, ) print(response) ``` #### Response ```json { "data": { "account_id": 19816, "average_fill_price": "149.95", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "my-ref-id-20251001-001", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.50", "order_type": "LIMIT", "quantity": "125", "side": "BUY", "status": "PENDING_REPLACE", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T14:10:00.000000000Z" }, "error": null, "metadata": { "request_id": "1d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a" } } ``` ## Cancel Open Order `v1.orders.cancel_open_order(strorder_id, OrderCancelOpenOrderParams**kwargs) -> OrderCancelOpenOrderResponse` **delete** `/v1/accounts/{account_id}/orders/{order_id}` Cancel a specific order ### Parameters - `account_id: int` - `order_id: str` ### Returns - `class OrderCancelOpenOrderResponse: …` - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.orders.cancel_open_order( order_id="order_id", account_id=0, ) print(response) ``` #### Response ```json { "data": { "account_id": 19816, "average_fill_price": "149.95", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "my-ref-id-20251001-001", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.50", "order_type": "LIMIT", "quantity": "125", "side": "BUY", "status": "PENDING_CANCEL", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T14:15:00.000000000Z" }, "error": null, "metadata": { "request_id": "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b" } } ``` ## Cancel All Open Orders `v1.orders.cancel_all_open_orders(intaccount_id, OrderCancelAllOpenOrdersParams**kwargs) -> OrderCancelAllOpenOrdersResponse` **delete** `/v1/accounts/{account_id}/orders` Cancel all orders for an account ### Parameters - `account_id: int` - `instrument_ids: Optional[Sequence[str]]` Comma-separated OEMS instrument UUIDs - `instrument_type: Optional[Literal["COMMON_STOCK", "PREFERRED_STOCK", "OPTION", 2 more]]` Filter by instrument type (e.g., COMMON_STOCK, OPTION) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `side: Optional[Literal["BUY", "SELL", "SELL_SHORT", "OTHER"]]` Filter by order side (BUY or SELL) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `type: Optional[Literal["MARKET", "LIMIT", "STOP", 4 more]]` Filter by order type (e.g., MARKET, LIMIT) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` ### Returns - `class OrderCancelAllOpenOrdersResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.orders.cancel_all_open_orders( account_id=0, ) print(response) ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": "149.95", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "019c0b48-b8fb-700d-8c5e-931d54555f54", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.00", "order_type": "LIMIT", "quantity": "100", "side": "BUY", "status": "PENDING_CANCEL", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T14:15:00.000000000Z" }, { "account_id": 19816, "average_fill_price": null, "created_at": "2025-10-31T14:00:00.000000000Z", "filled_quantity": "0", "id": "019c0b49-03af-70d1-8eeb-d69836c9840b", "instrument_id": "b2b3b4b5-c2c3-d2d3-e2e3-e4e5e6e7e8e9", "instrument_type": "COMMON_STOCK", "leaves_quantity": "200", "limit_price": "450.00", "order_type": "LIMIT", "quantity": "200", "side": "SELL", "status": "PENDING_CANCEL", "stop_price": null, "symbol": "MSFT", "time_in_force": "DAY", "updated_at": "2025-10-31T14:15:00.000000000Z" } ], "error": null, "metadata": { "request_id": "fb1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" } } ``` ## Domain Types ### Cancel Order Request - `class CancelOrderRequest: …` Request to cancel an existing order Note: In the API, order cancellation is done via DELETE request without a body. The order_id and account_id come from the URL path parameters. - `account_id: int` Account ID (from path parameter) - `order_id: str` Order ID to cancel (from path parameter) ### Instrument ID Or Symbol - `str` OEMS instrument UUID ### New Order Request - `class NewOrderRequest: …` Request to submit a new order (PlaceOrderRequest from spec) - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `order_type: RequestOrderType` Type of order - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `quantity: str` Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer) - `side: Side` Side of the order - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `time_in_force: RequestTimeInForce` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `id: Optional[str]` Optional client-provided unique ID (idempotency). Required to be unique per account. - `expires_at: Optional[datetime]` The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Allow trading outside regular trading hours. Some brokers disallow options outside RTH. - `instrument_id: Optional[InstrumentIDOrSymbol]` OEMS instrument UUID - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (required for LIMIT and STOP_LIMIT orders) - `position_effect: Optional[PositionEffect]` Required when instrument_type is OPTION. Specifies whether the order opens or closes a position. - `"OPEN"` - `"CLOSE"` - `stop_price: Optional[str]` Stop price (required for STOP and STOP_LIMIT orders) - `symbol: Optional[str]` Trading symbol. For equities, use the ticker symbol (e.g., "AAPL"). For options, use the OSI symbol (e.g., "AAPL 250117C00190000"). Either `symbol` or `instrument_id` must be provided. - `trailing_offset: Optional[str]` Trailing offset amount (required for trailing orders) - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type (PRICE or PERCENT_BPS) - `"PRICE"` - `"BPS"` ### Order - `class Order: …` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order List - `List[Order]` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Status - `Literal["PENDING_NEW", "NEW", "PARTIALLY_FILLED", 12 more]` Order status - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` ### Order Type - `Literal["MARKET", "LIMIT", "STOP", 4 more]` Order type - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` ### Position Effect - `Literal["OPEN", "CLOSE"]` Position effect for options orders - `"OPEN"` - `"CLOSE"` ### Queue State - `Literal["AWAITING_RELEASE", "RELEASED"]` Parent order queue or hold state. - `"AWAITING_RELEASE"` - `"RELEASED"` ### Request Order Type - `Literal["MARKET", "LIMIT", "STOP", 3 more]` Strict order-type enum for order submission/replacement requests. - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` ### Request Time In Force - `Literal["DAY", "GOOD_TILL_CANCEL", "IMMEDIATE_OR_CANCEL", 7 more]` Strict time-in-force enum for order submission/replacement requests. - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` ### Side - `Literal["BUY", "SELL", "SELL_SHORT", "OTHER"]` Side of an order - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` ### Time In Force - `Literal["DAY", "GOOD_TILL_CANCEL", "IMMEDIATE_OR_CANCEL", 8 more]` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` ### Trailing Offset Type - `Literal["PRICE", "BPS"]` Trailing offset type for trailing stop orders. - `"PRICE"` - `"BPS"` ### Order Get Orders Response - `class OrderGetOrdersResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Get Order By ID Response - `class OrderGetOrderByIDResponse: …` - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Submit Orders Response - `class OrderSubmitOrdersResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Replace Order Response - `class OrderReplaceOrderResponse: …` - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Cancel Open Order Response - `class OrderCancelOpenOrderResponse: …` - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Cancel All Open Orders Response - `class OrderCancelAllOpenOrdersResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. # Positions ## Get Positions `v1.positions.get_positions(intaccount_id, PositionGetPositionsParams**kwargs) -> PositionGetPositionsResponse` **get** `/v1/accounts/{account_id}/positions` Retrieves all positions for the specified trading account. ### Parameters - `account_id: int` - `instrument_ids: Optional[Sequence[str]]` Comma-separated OEMS instrument UUIDs - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `sort_by: Optional[Literal["SYMBOL", "INSTRUMENT_TYPE", "QUANTITY", 4 more]]` Field to sort by - `"SYMBOL"` - `"INSTRUMENT_TYPE"` - `"QUANTITY"` - `"MARKET_VALUE"` - `"POSITION_TYPE"` - `"UNREALIZED_PNL"` - `"DAILY_UNREALIZED_PNL"` - `sort_direction: Optional[Literal["ASC", "DESC"]]` Sort direction - `"ASC"` - `"DESC"` ### Returns - `class PositionGetPositionsResponse: …` - `data: PositionList` - `account_id: int` The account this position belongs to - `available_quantity: str` The quantity of a position that is free to be operated on. - `instrument_id: str` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: str` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: str` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: str` The trading symbol for the instrument - `avg_price: Optional[str]` The average price paid per share or contract for this position - `closing_price: Optional[str]` The closing price used to value the position for the last trading day - `closing_price_date: Optional[date]` The market date associated with `closing_price` - `cost_basis: Optional[str]` The total cost basis for this position - `daily_unrealized_pnl: Optional[str]` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: Optional[str]` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: Optional[str]` The current market price of the instrument - `underlying_instrument_id: Optional[str]` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: Optional[str]` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: Optional[str]` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.positions.get_positions( account_id=0, ) print(response) ``` #### Response ```json { "data": [ { "account_id": 19816, "available_quantity": "100", "avg_price": "145.00", "closing_price": "150.50", "closing_price_date": "2025-10-31", "cost_basis": "14500.00", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_price": "151.00", "instrument_type": "COMMON_STOCK", "market_value": "15050.00", "position_type": "LONG", "quantity": "100", "symbol": "AAPL", "unrealized_pnl": "550.00" }, { "account_id": 19816, "available_quantity": "100", "avg_price": "180.00", "closing_price": "180.00", "closing_price_date": "2025-10-30", "cost_basis": "-9000.00", "instrument_id": "d4d5d6d7-e4e5-f4f5-a4a5-a6a7a8a9aaab", "instrument_price": "178.50", "instrument_type": "COMMON_STOCK", "market_value": "-9000.00", "position_type": "SHORT", "quantity": "-50", "symbol": "TSLA", "unrealized_pnl": "75.00" }, { "account_id": 19816, "available_quantity": "100", "avg_price": "2.50", "closing_price": "2.70", "closing_price_date": "2025-10-30", "cost_basis": "2500.00", "instrument_id": "e5e6e7e8-f5f6-a5a6-b5b6-b7b8b9babcbe", "instrument_price": "2.72", "instrument_type": "OPTION", "market_value": "2700.00", "position_type": "LONG_CALL", "quantity": "10", "symbol": "AAPL250117C00190000", "underlying_instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "unrealized_pnl": "200.00" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3Rfc3ltYm9sPVRTM0E=", "page_number": 1, "request_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c", "total_items": 25, "total_pages": 3 } } ``` ## Close Positions `v1.positions.close_positions(intaccount_id, PositionClosePositionsParams**kwargs) -> PositionClosePositionsResponse` **delete** `/v1/accounts/{account_id}/positions` Delete all positions within an account. Closes all positions for the specified trading account. ### Parameters - `account_id: int` - `cancel_orders: Optional[bool]` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `class PositionClosePositionsResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.positions.close_positions( account_id=0, ) print(response) ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": null, "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "019c0b57-0850-7b0b-8a2c-5ee3fb5a5876", "instrument_id": "c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa", "instrument_type": "COMMON_STOCK", "leaves_quantity": "25", "limit_price": null, "order_type": "MARKET", "quantity": "25", "side": "SELL", "status": "PENDING_NEW", "stop_price": null, "symbol": "GOOG", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNMS" } ], "error": null, "metadata": { "request_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c" } } ``` ## Close Position `v1.positions.close_position(InstrumentIDOrSymbolinstrument_id, PositionClosePositionParams**kwargs) -> PositionClosePositionResponse` **delete** `/v1/accounts/{account_id}/positions/{instrument_id}` Delete a position within an account for an instrument. Retrieves orders generated to close the position. ### Parameters - `account_id: int` - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID - `cancel_orders: Optional[bool]` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `class PositionClosePositionResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.positions.close_position( instrument_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=0, ) print(response) ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": null, "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "019c0b56-2119-7482-a80f-5a2a316524d9", "instrument_id": "c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa", "instrument_type": "COMMON_STOCK", "leaves_quantity": "25", "limit_price": null, "order_type": "MARKET", "quantity": "25", "side": "SELL", "status": "PENDING_NEW", "stop_price": null, "symbol": "GOOG", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNMS" } ], "error": null, "metadata": { "request_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c" } } ``` ## List Position Instructions `v1.positions.get_position_instructions(intaccount_id, PositionGetPositionInstructionsParams**kwargs) -> PositionGetPositionInstructionsResponse` **get** `/v1/accounts/{account_id}/positions/instructions` Returns the current lifecycle state of the account's position instructions. Optionally filter by a specific contract. ### Parameters - `account_id: int` - `instrument_id: Optional[InstrumentIDOrSymbol]` Limit results to a single contract. Accepts the instrument id or the OSI symbol. ### Returns - `class PositionGetPositionInstructionsResponse: …` - `data: PositionInstructionList` - `id: str` Server-assigned id. Used as the path parameter on cancel. - `account_id: int` Account the instruction belongs to. - `instruction_id: str` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: str` Identifier of the options contract this instruction acts on. - `quantity: str` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: str` Options symbol (OSI) for display. - `accepted_quantity: Optional[str]` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: Optional[datetime]` When the instruction was first accepted by the service. - `rejection_reason: Optional[str]` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: Optional[datetime]` When the instruction's lifecycle state last changed. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.positions.get_position_instructions( account_id=0, ) print(response) ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "account_id": 122503, "instruction_id": "ui-20260424-001", "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "quantity": "1", "status": "SENT", "symbol": "AAPL 280121C00195000", "accepted_quantity": null, "created_at": "2026-04-24T14:30:00Z", "rejection_reason": null, "updated_at": "2026-04-24T14:30:00Z" } ] } ``` ## Submit Position Instructions `v1.positions.submit_position_instructions(intaccount_id, PositionSubmitPositionInstructionsParams**kwargs) -> PositionSubmitPositionInstructionsResponse` **post** `/v1/accounts/{account_id}/positions/instructions` Submit one or more position instructions (Exercise, Do-Not-Exercise, Contrary Exercise Advice) against the account. Batch semantics: - **All rows accepted** → `200 OK`. Every row is in `data` with `status = SENT`. - **Partial success** → `207 Multi-Status`. `data` contains every row; rejected rows carry `status = ENGINE_REJECTED` (or `REJECTED`) and `rejection_reason`. The top-level `error` summarizes the batch failure. - **All rows rejected** → `4xx`/`5xx` error response. The HTTP status reflects the underlying cause: `409` for duplicate `instruction_id`, `400` for validation failures such as DNE/CEA on a non-expiry day, `503` if the clearing service is unavailable. No `data` is returned. Pre-flight validation (unknown `instrument_id`, unencodable `quantity`) short-circuits the whole batch with a `4xx` before any row is submitted. ### Parameters - `account_id: int` - `instructions: Iterable[Instruction]` - `instruction_type: PositionInstructionType` The action to take. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: str` Identifier of the options contract to act on. Unknown ids return 404. - `quantity: str` Number of contracts to include in the instruction. - `instruction_id: Optional[str]` Caller-supplied idempotency key. Echoed on the response. The server generates a unique id when omitted. ### Returns - `class PositionSubmitPositionInstructionsResponse: …` - `data: PositionInstructionList` - `id: str` Server-assigned id. Used as the path parameter on cancel. - `account_id: int` Account the instruction belongs to. - `instruction_id: str` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: str` Identifier of the options contract this instruction acts on. - `quantity: str` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: str` Options symbol (OSI) for display. - `accepted_quantity: Optional[str]` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: Optional[datetime]` When the instruction was first accepted by the service. - `rejection_reason: Optional[str]` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: Optional[datetime]` When the instruction's lifecycle state last changed. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.positions.submit_position_instructions( account_id=0, instructions=[{ "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "quantity": "1", }], ) print(response) ``` #### Response ```json { "data": [ { "account_id": 122503, "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "instruction_id": "ui-20260424-001", "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01", "quantity": "1", "status": "SENT", "symbol": "AAPL 280121C00195000" } ], "metadata": { "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd01" } } ``` ## Cancel Position Instruction `v1.positions.cancel_position_instruction(strinstruction_id, PositionCancelPositionInstructionParams**kwargs) -> PositionCancelPositionInstructionResponse` **delete** `/v1/accounts/{account_id}/positions/instructions/{instruction_id}` Cancel an outstanding position instruction by its server-assigned `id`. Returns the updated instruction with status `CANCEL_REQUESTED`. The terminal `CANCELLED` or `CANCEL_FAILED` state arrives asynchronously and is observable via subsequent GETs. ### Parameters - `account_id: int` - `instruction_id: str` ### Returns - `class PositionCancelPositionInstructionResponse: …` - `data: PositionInstruction` A position instruction and its current lifecycle state. - `id: str` Server-assigned id. Used as the path parameter on cancel. - `account_id: int` Account the instruction belongs to. - `instruction_id: str` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: str` Identifier of the options contract this instruction acts on. - `quantity: str` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: str` Options symbol (OSI) for display. - `accepted_quantity: Optional[str]` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: Optional[datetime]` When the instruction was first accepted by the service. - `rejection_reason: Optional[str]` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: Optional[datetime]` When the instruction's lifecycle state last changed. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.positions.cancel_position_instruction( instruction_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id=0, ) print(response) ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": { "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "account_id": 122503, "instruction_id": "ui-20260424-001", "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "quantity": "1", "status": "SENT", "symbol": "AAPL 280121C00195000", "accepted_quantity": null, "created_at": "2026-04-24T14:30:00Z", "rejection_reason": null, "updated_at": "2026-04-24T14:30:00Z" } } ``` ## Domain Types ### Position - `class Position: …` Represents a holding of a particular instrument in an account - `account_id: int` The account this position belongs to - `available_quantity: str` The quantity of a position that is free to be operated on. - `instrument_id: str` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: str` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: str` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: str` The trading symbol for the instrument - `avg_price: Optional[str]` The average price paid per share or contract for this position - `closing_price: Optional[str]` The closing price used to value the position for the last trading day - `closing_price_date: Optional[date]` The market date associated with `closing_price` - `cost_basis: Optional[str]` The total cost basis for this position - `daily_unrealized_pnl: Optional[str]` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: Optional[str]` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: Optional[str]` The current market price of the instrument - `underlying_instrument_id: Optional[str]` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: Optional[str]` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: Optional[str]` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Instruction - `class PositionInstruction: …` A position instruction and its current lifecycle state. - `id: str` Server-assigned id. Used as the path parameter on cancel. - `account_id: int` Account the instruction belongs to. - `instruction_id: str` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: str` Identifier of the options contract this instruction acts on. - `quantity: str` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: str` Options symbol (OSI) for display. - `accepted_quantity: Optional[str]` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: Optional[datetime]` When the instruction was first accepted by the service. - `rejection_reason: Optional[str]` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: Optional[datetime]` When the instruction's lifecycle state last changed. ### Position Instruction List - `List[PositionInstruction]` - `id: str` Server-assigned id. Used as the path parameter on cancel. - `account_id: int` Account the instruction belongs to. - `instruction_id: str` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: str` Identifier of the options contract this instruction acts on. - `quantity: str` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: str` Options symbol (OSI) for display. - `accepted_quantity: Optional[str]` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: Optional[datetime]` When the instruction was first accepted by the service. - `rejection_reason: Optional[str]` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: Optional[datetime]` When the instruction's lifecycle state last changed. ### Position Instruction Status - `Literal["SENT", "ACCEPTED", "REJECTED", 5 more]` Lifecycle status of a position instruction. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` ### Position Instruction Type - `Literal["EXERCISE", "DO_NOT_EXERCISE", "CONTRARY_EXERCISE"]` The action to take against an options position. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` ### Position List - `List[Position]` - `account_id: int` The account this position belongs to - `available_quantity: str` The quantity of a position that is free to be operated on. - `instrument_id: str` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: str` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: str` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: str` The trading symbol for the instrument - `avg_price: Optional[str]` The average price paid per share or contract for this position - `closing_price: Optional[str]` The closing price used to value the position for the last trading day - `closing_price_date: Optional[date]` The market date associated with `closing_price` - `cost_basis: Optional[str]` The total cost basis for this position - `daily_unrealized_pnl: Optional[str]` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: Optional[str]` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: Optional[str]` The current market price of the instrument - `underlying_instrument_id: Optional[str]` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: Optional[str]` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: Optional[str]` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Type - `Literal["LONG", "SHORT", "LONG_CALL", 3 more]` Position type classification - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` ### Position Get Positions Response - `class PositionGetPositionsResponse: …` - `data: PositionList` - `account_id: int` The account this position belongs to - `available_quantity: str` The quantity of a position that is free to be operated on. - `instrument_id: str` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: str` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: str` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: str` The trading symbol for the instrument - `avg_price: Optional[str]` The average price paid per share or contract for this position - `closing_price: Optional[str]` The closing price used to value the position for the last trading day - `closing_price_date: Optional[date]` The market date associated with `closing_price` - `cost_basis: Optional[str]` The total cost basis for this position - `daily_unrealized_pnl: Optional[str]` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: Optional[str]` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: Optional[str]` The current market price of the instrument - `underlying_instrument_id: Optional[str]` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: Optional[str]` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: Optional[str]` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Close Positions Response - `class PositionClosePositionsResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Position Close Position Response - `class PositionClosePositionResponse: …` - `data: OrderList` - `id: str` Engine-assigned unique identifier for this order (UUID). - `account_id: int` Account placing the order - `client_order_id: str` Client-provided identifier echoed back (FIX tag 11). - `created_at: datetime` Timestamp when order was created (UTC) - `filled_quantity: str` Cumulative filled quantity - `instrument_id: str` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: str` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: str` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: str` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: datetime` Timestamp of the most recent update (UTC) - `venue: str` MIC code of the venue where the order is routed - `average_fill_price: Optional[str]` Average fill price across all executions - `details: Optional[List[str]]` Contains execution, rejection or cancellation details, if any - `expires_at: Optional[datetime]` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: Optional[bool]` Whether the order is eligible for extended-hours trading. - `limit_offset: Optional[str]` Limit offset for trailing stop-limit orders (signed) - `limit_price: Optional[str]` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: Optional[QueueState]` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: Optional[datetime]` Scheduled release time for orders awaiting release. - `stop_price: Optional[str]` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: Optional[str]` Current trailing limit price computed by the trailing strategy - `trailing_offset: Optional[str]` Trailing offset amount for trailing orders - `trailing_offset_type: Optional[TrailingOffsetType]` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: Optional[str]` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: Optional[str]` Trailing watermark price for trailing orders - `trailing_watermark_ts: Optional[datetime]` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: Optional[str]` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Position Get Position Instructions Response - `class PositionGetPositionInstructionsResponse: …` - `data: PositionInstructionList` - `id: str` Server-assigned id. Used as the path parameter on cancel. - `account_id: int` Account the instruction belongs to. - `instruction_id: str` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: str` Identifier of the options contract this instruction acts on. - `quantity: str` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: str` Options symbol (OSI) for display. - `accepted_quantity: Optional[str]` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: Optional[datetime]` When the instruction was first accepted by the service. - `rejection_reason: Optional[str]` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: Optional[datetime]` When the instruction's lifecycle state last changed. ### Position Submit Position Instructions Response - `class PositionSubmitPositionInstructionsResponse: …` - `data: PositionInstructionList` - `id: str` Server-assigned id. Used as the path parameter on cancel. - `account_id: int` Account the instruction belongs to. - `instruction_id: str` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: str` Identifier of the options contract this instruction acts on. - `quantity: str` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: str` Options symbol (OSI) for display. - `accepted_quantity: Optional[str]` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: Optional[datetime]` When the instruction was first accepted by the service. - `rejection_reason: Optional[str]` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: Optional[datetime]` When the instruction's lifecycle state last changed. ### Position Cancel Position Instruction Response - `class PositionCancelPositionInstructionResponse: …` - `data: PositionInstruction` A position instruction and its current lifecycle state. - `id: str` Server-assigned id. Used as the path parameter on cancel. - `account_id: int` Account the instruction belongs to. - `instruction_id: str` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: str` Identifier of the options contract this instruction acts on. - `quantity: str` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: str` Options symbol (OSI) for display. - `accepted_quantity: Optional[str]` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: Optional[datetime]` When the instruction was first accepted by the service. - `rejection_reason: Optional[str]` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: Optional[datetime]` When the instruction's lifecycle state last changed. # Watchlist ## Get Watchlists `v1.watchlist.get_watchlists(WatchlistGetWatchlistsParams**kwargs) -> WatchlistGetWatchlistsResponse` **get** `/v1/watchlists` List watchlists for the authenticated user ### Parameters - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class WatchlistGetWatchlistsResponse: …` - `data: WatchlistEntryList` - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.get_watchlists() print(response) ``` #### Response ```json { "data": [ { "created_at": "2025-01-15T10:00:00.000000000Z", "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Tech Stocks" }, { "created_at": "2025-01-10T14:30:00.000000000Z", "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Dividend Portfolio" } ], "error": null, "metadata": { "next_page_token": null, "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "total_items": 2, "total_pages": 1 } } ``` ## Get Watchlist By ID `v1.watchlist.get_watchlist_by_id(strwatchlist_id) -> WatchlistGetWatchlistByIDResponse` **get** `/v1/watchlists/{watchlist_id}` Get a watchlist by ID with all its items ### Parameters - `watchlist_id: str` ### Returns - `class WatchlistGetWatchlistByIDResponse: …` - `data: WatchlistDetail` Detailed watchlist with all items - `id: str` Watchlist ID - `created_at: datetime` Creation timestamp - `items: List[WatchlistItemEntry]` Items in the watchlist - `id: str` Item ID - `added_at: datetime` When the item was added - `added_price: Optional[str]` Price when the item was added - `instrument: Optional[Instrument]` Instrument details - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: Optional[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments - `name: str` Watchlist name ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.get_watchlist_by_id( "550e8400-e29b-41d4-a716-446655440000", ) print(response) ``` #### Response ```json { "data": { "created_at": "2025-01-15T10:00:00.000000000Z", "id": "550e8400-e29b-41d4-a716-446655440000", "items": [ { "added_at": "2025-01-16T09:30:00.000000000Z", "added_price": "150.25", "id": "660e8400-e29b-41d4-a716-446655440001", "instrument": { "country_of_issue": "US", "currency": "USD", "easy_to_borrow": true, "id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "is_liquidation_only": false, "is_marginable": true, "is_restricted": false, "is_short_prohibited": false, "is_threshold_security": false, "is_tradable": true, "name": "Apple Inc.", "symbol": "AAPL", "venue": "XNMS" } } ], "name": "Tech Stocks" }, "error": null, "metadata": { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } } ``` ## Create Watchlist `v1.watchlist.create_watchlist(WatchlistCreateWatchlistParams**kwargs) -> WatchlistCreateWatchlistResponse` **post** `/v1/watchlists` Create Watchlist ### Parameters - `name: str` The desired watchlist name. ### Returns - `class WatchlistCreateWatchlistResponse: …` - `data: WatchlistEntry` Represents a user watchlist. - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.create_watchlist( name="name", ) print(response) ``` #### Response ```json { "data": { "created_at": "2025-01-23T12:00:00.000000000Z", "id": "770e8400-e29b-41d4-a716-446655440002", "name": "Growth Stocks" }, "error": null, "metadata": { "request_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg" } } ``` ## Delete Watchlist `v1.watchlist.delete_watchlist(strwatchlist_id) -> object` **delete** `/v1/watchlists/{watchlist_id}` Delete a watchlist and all its items ### Parameters - `watchlist_id: str` ### Returns - `object` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.delete_watchlist( "550e8400-e29b-41d4-a716-446655440000", ) print(response) ``` #### Response ```json { "data": null, "metadata": { "request_id": "cb824f1b-ea6e-4045-8169-9503be2b24d7" } } ``` ## Add Watchlist Item `v1.watchlist.add_watchlist_item(strwatchlist_id, WatchlistAddWatchlistItemParams**kwargs) -> WatchlistAddWatchlistItemResponse` **post** `/v1/watchlists/{watchlist_id}/items` Add an instrument to a watchlist ### Parameters - `watchlist_id: str` - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Returns - `class WatchlistAddWatchlistItemResponse: …` - `data: AddWatchlistItemData` Response data for adding a watchlist item - `item_id: str` ID of the created item ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.add_watchlist_item( watchlist_id="550e8400-e29b-41d4-a716-446655440000", instrument_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response) ``` #### Response ```json { "data": { "item_id": "770e8400-e29b-41d4-a716-446655440002" }, "error": null, "metadata": { "request_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg" } } ``` ## Delete Watchlist Item `v1.watchlist.delete_watchlist_item(stritem_id, WatchlistDeleteWatchlistItemParams**kwargs) -> object` **delete** `/v1/watchlists/{watchlist_id}/items/{item_id}` Delete an instrument from a watchlist ### Parameters - `watchlist_id: str` - `item_id: str` ### Returns - `object` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.delete_watchlist_item( item_id="660e8400-e29b-41d4-a716-446655440001", watchlist_id="550e8400-e29b-41d4-a716-446655440000", ) print(response) ``` #### Response ```json { "data": null, "metadata": { "request_id": "5b0709e3-5868-4116-9a84-26f1b8c30503" } } ``` ## Domain Types ### Add Watchlist Item Data - `class AddWatchlistItemData: …` Response data for adding a watchlist item - `item_id: str` ID of the created item ### Watchlist Detail - `class WatchlistDetail: …` Detailed watchlist with all items - `id: str` Watchlist ID - `created_at: datetime` Creation timestamp - `items: List[WatchlistItemEntry]` Items in the watchlist - `id: str` Item ID - `added_at: datetime` When the item was added - `added_price: Optional[str]` Price when the item was added - `instrument: Optional[Instrument]` Instrument details - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: Optional[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments - `name: str` Watchlist name ### Watchlist Entry - `class WatchlistEntry: …` Represents a user watchlist. - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Watchlist Entry List - `List[WatchlistEntry]` - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Watchlist Item Entry - `class WatchlistItemEntry: …` A single item in a watchlist - `id: str` Item ID - `added_at: datetime` When the item was added - `added_price: Optional[str]` Price when the item was added - `instrument: Optional[Instrument]` Instrument details - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: Optional[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Watchlist Get Watchlists Response - `class WatchlistGetWatchlistsResponse: …` - `data: WatchlistEntryList` - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Watchlist Get Watchlist By ID Response - `class WatchlistGetWatchlistByIDResponse: …` - `data: WatchlistDetail` Detailed watchlist with all items - `id: str` Watchlist ID - `created_at: datetime` Creation timestamp - `items: List[WatchlistItemEntry]` Items in the watchlist - `id: str` Item ID - `added_at: datetime` When the item was added - `added_price: Optional[str]` Price when the item was added - `instrument: Optional[Instrument]` Instrument details - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` The expiration date for options instruments - `instrument_type: Optional[SecurityType]` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: Optional[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: Optional[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments - `name: str` Watchlist name ### Watchlist Create Watchlist Response - `class WatchlistCreateWatchlistResponse: …` - `data: WatchlistEntry` Represents a user watchlist. - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Watchlist Add Watchlist Item Response - `class WatchlistAddWatchlistItemResponse: …` - `data: AddWatchlistItemData` Response data for adding a watchlist item - `item_id: str` ID of the created item # Websocket ## Websocket Handler `v1.websocket.websocket_handler()` **get** `/v1/ws` Upgrade the HTTP connection to a WebSocket and echo incoming messages. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) client.v1.websocket.websocket_handler() ```