--- title: "Search Instruments" method: GET path: "/v1/instruments/search" tags: ["Instruments"] --- # Search Instruments `GET /v1/instruments/search` ## Request - Base URL: `https://api.clearstreet.com` - URL: `https://api.clearstreet.com/v1/instruments/search` - Auth: HTTP bearer Search instruments by symbol, alternate identifier, or company name. The `q` parameter is case-insensitive and supports ticker symbols, alternate identifiers such as CUSIP, ISIN, and OPRA root, and company names for non-option instruments. Results are ranked by match quality plus instrument quality signals and relevance. Defaults to the `EQUITY` asset class (common stocks, preferred shares, ADRs, ETFs, and exchange-traded mutual funds). Pass `asset_class=OPTION` to search option contracts: by full OSI symbol, by an OSI prefix (root + `YYMMDD` expiry, e.g. `AAPL 261217`), or by a root-scoped phrase such as `AAPL Dec 250 call`. ## Query parameters - `q` string, required - `asset_class` string - `include_inactive` boolean - `include_ptp` boolean - `currency` string - `country` string - `page_size` integer - `page_token` string, byte: Base64URL-encoded pagination token ## Response `200` Ranked list of matching instruments - 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` InstrumentCore[], required - `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 ## Other responses - `400`: Missing or invalid query parameters - `500`: Internal server error - `503`: Instrument data is not ready yet ## Changes - **2026-10-22** `8cd2eff4763b`: 1 info - added the optional property `allOf[subschema #2]/data/items/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/shortable_attribute` to the response with the `200` status - **2026-10-16** `1bd9eddeffc8`: 2 info - added the optional property `allOf[subschema #2]/data/items/cax_adjusted_previous_close` to the response with the `200` status - added the optional property `allOf[subschema #2]/data/items/tick_rules` to the response with the `200` status - **2026-07-20** `3d9841be8847`: 2 warning - removed the optional property `allOf[subschema #2]/data/items/expiry` from the response with the `200` status - removed the optional property `allOf[subschema #2]/data/items/strike_price` from the response with the `200` status - **2026-07-17** `12dd2417df82`: 1 warning - added the new `INDEX` enum value to the `allOf[subschema #2]/data/items/instrument_type/oneOf[#/components/schemas/SecurityType]/` response property for the response status `200` [Operation history](https://skmtc.dev/clear-street/apis/clear-street-trading-api/changes/v1/instruments/search/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)