CLclear-street
Positions

Get Position Instructions

Changed on

Returns the current lifecycle state of the account's position instructions. Optionally filter by a specific contract.

Note: instructions that fail pre-acceptance validation on POST — duplicates, DO_NOT_EXERCISE / CONTRARY_EXERCISE on a non-expiry day, insufficient position, or an unresolvable instrument — are rejected (with status = REJECTED and a rejection_reason) without being persisted, so they surface only in the POST response and never appear in this list.

get/v1/accounts/{account_id}/positions/instructions

Request

  • Base URL
    https://api.clearstreet.com
  • Auth
    HTTP bearer

Path parameters

account_idinteger required

Account identifier

Query parameters

instrument_idstring

Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.

Limit results to a single contract. Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).

underlying_instrument_idstring

Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.

Limit results to instructions whose contract has this underlier. Instrument ID (UUID) or symbol (equity ticker or OSI option symbol). Combined with instrument_id as a logical AND when both are supplied.

Response

Position instructions

Example response

{
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero"
  },
  "metadata": {
    "page_number": 1,
    "total_items": 42,
    "total_pages": 5
  },
  "data": [
    {
      "accepted_quantity": null,
      "account_id": 122503,
      "client_instruction_id": "ui-20260424-001",
      "created_at": "2026-04-24T14:30:00Z",
      "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
      "instruction_type": "EXERCISE",
      "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
      "quantity": "1",
      "rejection_reason": null,
      "status": "SENT",
      "symbol": "AAPL  280121C00195000",
      "updated_at": "2026-04-24T14:30:00Z"
    }
  ]
}

Changes

  • 1bd9eddeffc8Revision changes
    • breaking

      for the query request parameter instrument_id, the minLength was increased from 0 to 1

    • breaking

      removed the required property /// from the response with the status

    • info

      added the new optional query request parameter underlying_instrument_id

    • info

      for the query request parameter instrument_id, the type was generalized from no type to string

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the required property /// to the response with the status

  • 99644beba9d7Revision changes
    • info

      removed the ENGINE_REJECTED enum value from the /// response property for the response status