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

Search Instruments

v1.instruments.search_instruments(InstrumentSearchInstrumentsParams**kwargs) -> InstrumentSearchInstrumentsResponse
GET/v1/instruments/search

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, OPRA root, and CMS identifiers, and company names for non-option instruments. Results are ranked by match quality plus instrument quality signals including log-scaled ADV, listing status, marginability, easy-to-borrow status, and OTC, restricted, and liquidation-only penalties. 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 symbol or alternate identifier.

ParametersExpand Collapse
q: str

Search term applied case-insensitively to ticker symbols, alternate identifiers (CUSIP, ISIN, OPRA root, CMS), and company names for non-option instruments. Option searches match symbols and alternate identifiers.

asset_class: Optional[str]

Comma-separated asset classes (EQUITY|OPTION|WARRANT|BOND|FX|OTHER). Defaults to EQUITY.

country: Optional[str]

Optional listing-country filter (e.g., US).

currency: Optional[str]

Optional ISO currency filter (e.g., USD).

include_inactive: Optional[bool]

Include inactive instruments. Default false.

include_restricted: Optional[bool]

Include restricted instruments. Default true (penalized in ranking).

page_size: Optional[int]

The number of items to return per page. Only used when page_token is not provided.

formatint64
maximum100
minimum1
page_token: Optional[Union[str, Base64FileInput]]

Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored.

formatbyte
ReturnsExpand Collapse
class InstrumentSearchInstrumentsResponse: …
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.

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

Search Instruments

from clear_street import ClearStreet

client = ClearStreet(
    api_key="My API Key",
)
response = client.v1.instruments.search_instruments(
    q="q",
)
print(response)
{
  "data": [
    {
      "currency": "USD",
      "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b",
      "instrument_type": "COMMON_STOCK",
      "is_marginable": true,
      "name": "Apple Inc.",
      "symbol": "AAPL",
      "venue": "XNMS"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "..."
  }
}
{
  "data": [
    {
      "country_of_issue": "US",
      "currency": "USD",
      "easy_to_borrow": true,
      "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b",
      "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"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e"
  }
}
Returns Examples
{
  "data": [
    {
      "currency": "USD",
      "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b",
      "instrument_type": "COMMON_STOCK",
      "is_marginable": true,
      "name": "Apple Inc.",
      "symbol": "AAPL",
      "venue": "XNMS"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "..."
  }
}
{
  "data": [
    {
      "country_of_issue": "US",
      "currency": "USD",
      "easy_to_borrow": true,
      "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b",
      "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"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e"
  }
}