--- title: "Get Watchlist By ID" method: GET path: "/v1/watchlists/{watchlist_id}" tags: ["Watchlist"] --- # Get Watchlist By ID `GET /v1/watchlists/{watchlist_id}` ## Request - Base URL: `https://api.clearstreet.com` - URL: `https://api.clearstreet.com/v1/watchlists/{watchlist_id}` - Auth: HTTP bearer Get a watchlist by ID with all its items ## Path parameters - `watchlist_id` string, uuid, required ## Response `200` Watchlist details with items - object - `error` ApiError: A direct mapping of tonic::Status, for use in HTTP responses. - `code` integer, required: The error code is used to identify the nature of the error. It corresponds to an HTTP status code. - `details` object[] - `message` string, required: A human-readable message providing more details about the error. - `metadata` ResponseMetadata, required: Metadata for the response. This will always contain a request ID which can be used to identify the request to Clear Street for tracing, and optionally may include pagination data. - `next_page_token` string, byte, nullable: Base64URL-encoded pagination token - `page_number` integer, nullable: Pagination. Included if this was a GET (list) response - `previous_page_token` string, byte, nullable: Base64URL-encoded pagination token - `request_id` string, required: A unique ID for this request, generated upon ingestion of the request. - `total_items` integer, nullable: Total number of items available (not just in this page). - `total_pages` integer, nullable: Total number of pages available. - `data` WatchlistDetail, required: Detailed watchlist with all items - `created_at` string, date-time, required: The timestamp when the watchlist was created. - `id` string, uuid, required: The unique identifier for the watchlist. - `items` WatchlistItemEntry[], required: Items in the watchlist - `added_at` string, date-time, required: When the item was added - `added_price` string, nullable: Price when the item was added When a null/undefined value is observed, it indicates that there is no available data. - `id` string, uuid, required: Item ID - `instrument` Instrument: Represents a tradable financial instrument. - `adv` string, nullable: Average daily share volume from the security definition. When a null/undefined value is observed, it indicates that there is no available data. - `cax_adjusted_previous_close` string, nullable: Corporate-action-adjusted last close; present only when an adjustment exists for the previous_close date. When a null/undefined value is observed, it indicates that there is no available data. - `country_of_issue` string, required: The ISO country code of the instrument's issue - `currency` string, required: The ISO currency code in which the instrument is traded - `easy_to_borrow` boolean, required: Indicates if the instrument is classified as Easy-To-Borrow - `id` string, uuid, required: Unique instrument identifier (UUID) - `instrument_type` 'COMMON_STOCK' | 'INDEX' | 'OPTION' | 'CASH': Security type - `is_fractionable` boolean, required: Indicates if the instrument supports fractional-quantity orders - `is_liquidation_only` boolean, required: Indicates if the instrument is liquidation only and cannot be bought - `is_marginable` boolean, required: Indicates if the instrument is marginable - `is_ptp` boolean, required: Indicates if the instrument is a publicly traded partnership (PTP). PTP sales are subject to a 10% withholding tax for non-US tax residents. - `is_short_prohibited` boolean, required: Indicates if short selling is prohibited for the instrument. This is a standing property of the security. For the live Rule 201 circuit breaker, see `short_sale_restricted` on the market-data snapshot. - `is_threshold_security` boolean, required: Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable` boolean, required: Indicates if the instrument is tradable - `long_margin_rate` string, nullable: The percent of a long position's value you must post as margin When a null/undefined value is observed, it indicates that there is no available data. - `name` string, nullable: The full name of the instrument or its issuer When a null/undefined value is observed, it indicates that there is no available data. - `not_shortable_reasons` NotShortableReason[], nullable: Why the instrument is `NOT_SHORTABLE`: every reason that applies, using the same codes as the `type` of the equivalent order-preview errors. Omitted unless `shortable_attribute` is `NOT_SHORTABLE`. When a null/undefined value is observed, it indicates it does not apply. - `notional_adv` string, nullable: Notional average daily volume (ADV multiplied by the cax-adjusted close when present, the raw previous close otherwise). When a null/undefined value is observed, it indicates that there is no available data. - `previous_close` string, nullable: Last close price from the security definition. When a null/undefined value is observed, it indicates that there is no available data. - `short_margin_rate` string, nullable: The percent of a short position's value you must post as margin When a null/undefined value is observed, it indicates that there is no available data. - `shortable_attribute` 'EASY_TO_BORROW' | 'HARD_TO_BORROW' | 'NOT_SHORTABLE': How readily a tradable equity can be shorted. - `symbol` string, required: The trading symbol for the instrument - `tick_rules` TickRule[]: Price bands this instrument quotes on, ascending. A price outside every band is not valid. Absent when we have no schedule for it, which includes an option whose penny-program status our reference data never supplied. - `end_price` string, nullable: Upper bound of the band, exclusive. Absent when the band runs to infinity. When a null/undefined value is observed, it indicates it does not apply. - `start_price` string, required: Lowest price in the band, inclusive. - `tick_size` string, required: Minimum price increment within the band. - `venue` string, required: The MIC code of the primary listing venue - `options_contract_expiry_dates` OptionExpiryDate[], nullable: Available options expiration dates for this instrument, each annotated with which settlement cycles have listed contracts on it. Present only when `include_options_expiry_dates=true` in the request. When a null/undefined value is observed, it indicates it does not apply. - `date` string, date, required: The expiration date. - `has_settles_on_close` boolean, required: Whether this date has at least one listed contract that settles at the close (PM settlement) -- the standard cycle. - `has_settles_on_open` boolean, required: Whether this date has at least one contract that settles on the opening print (AM settlement) and can still be traded. AM-settled contracts stop trading at the close of the business day before settlement, so this turns false before the expiration date arrives. A date leaves the list once no contract on it can be traded in either settlement cycle. - `options_expiry_dates` string[], nullable: Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. Deprecated: use `options_contract_expiry_dates`, which carries the same dates annotated with settlement-cycle information. When a null/undefined value is observed, it indicates it does not apply. - `name` string, required: The user-provided watchlist name. ## Other responses - `404`: Watchlist not found - `500`: Internal server error ## Changes - **2026-10-22** `8cd2eff4763b`: 1 info - added the optional property `allOf[subschema #2]/data/items/items/instrument/oneOf[#/components/schemas/Instrument]/allOf[subschema #1]/not_shortable_reasons` to the response with the `200` status - **2026-10-21** `49c5c6b23633`: 1 info - added the optional property `allOf[subschema #2]/data/items/items/instrument/oneOf[#/components/schemas/Instrument]/allOf[subschema #1]/shortable_attribute` to the response with the `200` status - **2026-10-16** `1bd9eddeffc8`: 2 info - added `subschema #1, subschema #2` to the `allOf[subschema #2]/data/items/items/instrument/oneOf[#/components/schemas/Instrument]/` response property `allOf` list for the response status `200` - removed `subschema #1, subschema #2` from the `allOf[subschema #2]/data/items/items/instrument/oneOf[#/components/schemas/Instrument]/` response property `allOf` list for the response status `200` - **2026-07-20** `3d9841be8847`: 2 warning - removed the optional property `allOf[subschema #2]/data/items/items/instrument/oneOf[#/components/schemas/Instrument]/allOf[subschema #1]/expiry` from the response with the `200` status - removed the optional property `allOf[subschema #2]/data/items/items/instrument/oneOf[#/components/schemas/Instrument]/allOf[subschema #1]/strike_price` from the response with the `200` status - …earlier changes not shown [Operation history](https://skmtc.dev/clear-street/apis/clear-street-trading-api/changes/v1/watchlists/:watchlist_id/get.md) --- [API](https://skmtc.dev/clear-street/apis/clear-street-trading-api.md) - [All operations](https://skmtc.dev/clear-street/apis/clear-street-trading-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clear-street/apis/clear-street-trading-api/revisions/52e77ea7d731?raw)