Skip to content
Clear Street Clear Street
Get started
API Reference
V1
Watchlist

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

ParametersExpand Collapse
watchlist_id: str
ReturnsExpand Collapse
class WatchlistGetWatchlistByIDResponse: …

Detailed watchlist with all items

id: str

Watchlist ID

formatuuid
created_at: datetime

Creation timestamp

formatdate-time
items: List[WatchlistItemEntry]

Items in the watchlist

id: str

Item ID

formatuuid
added_at: datetime

When the item was added

formatdate-time
added_price: Optional[str]

Price when the item was added

instrument: Optional[Instrument]

Instrument details

id: str

Unique OEMS instrument identifier (UUID)

formatuuid
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

formatdate
instrument_type: Optional[SecurityType]

The type of security (e.g., Common Stock, ETF)

One of the following:
"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

Get Watchlist By ID

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)
{
  "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"
  }
}
{
  "error": {
    "code": 404,
    "message": "Some requested entity was not found"
  },
  "metadata": {
    "request_id": "8e6cec7b-342c-4231-a4f0-e650b48db699"
  }
}
Returns Examples
{
  "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"
  }
}
{
  "error": {
    "code": 404,
    "message": "Some requested entity was not found"
  },
  "metadata": {
    "request_id": "8e6cec7b-342c-4231-a4f0-e650b48db699"
  }
}