# 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.