Get Watchlist By ID

$ clear-street v1:watchlist get-watchlist-by-id

GET/v1/watchlists/{watchlist_id}

Get a watchlist by ID with all its items

ParametersExpand Collapse

--watchlist-id: string

Watchlist ID

ReturnsExpand Collapse

V1WatchlistGetWatchlistByIDResponse: BaseResponse { metadata, error }

data: object { id, created_at, items, name }

Detailed watchlist with all items

id: string

Watchlist ID

created_at: string

Creation timestamp

items: array of WatchlistItemEntry { id, added_at, added_price, instrument }

Items in the watchlist

id: string

Item ID

added_at: string

When the item was added

added_price: optional string

Price when the item was added

instrument: optional object { id, country_of_issue, currency, 19 more }

Instrument details

id: string

Unique OEMS instrument identifier (UUID)

country_of_issue: string

The ISO country code of the instrument’s issue

currency: string

The ISO currency code in which the instrument is traded

easy_to_borrow: boolean

Indicates if the instrument is classified as Easy-To-Borrow

is_liquidation_only: boolean

Indicates if the instrument is liquidation only and cannot be bought

is_marginable: boolean

Indicates if the instrument is marginable

is_restricted: boolean

Indicates if the instrument is restricted from trading

is_short_prohibited: boolean

Indicates if short selling is prohibited for the instrument

is_threshold_security: boolean

Indicates if the instrument is on the Regulation SHO Threshold Security List

is_tradable: boolean

Indicates if the instrument is tradable

symbol: string

The trading symbol for the instrument

venue: string

The MIC code of the primary listing venue

adv: optional string

Average daily share volume from the security definition.

expiry: optional string

The expiration date for options instruments

instrument_type: optional "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more

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

"COMMON_STOCK"

"PREFERRED_STOCK"

"OPTION"

"CASH"

"OTHER"

long_margin_rate: optional string

The percent of a long position’s value you must post as margin

name: optional string

The full name of the instrument or its issuer

notional_adv: optional string

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 array of string

Available options expiration dates for this instrument. Present only when include_options_expiry_dates=true in the request.

previous_close: optional string

Last close price from the security definition.

short_margin_rate: optional string

The percent of a short position’s value you must post as margin

strike_price: optional string

The strike price for options instruments

name: string

Watchlist name

Get Watchlist By ID

clear-street v1:watchlist get-watchlist-by-id \
  --api-key 'My API Key' \
  --watchlist-id 550e8400-e29b-41d4-a716-446655440000

{
  "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"
  }
}