## Search Instruments

`$ clear-street v1:instruments search-instruments`

**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.

### Parameters

- `--q: string`

  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 string`

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

- `--country: optional string`

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

- `--currency: optional string`

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

- `--include-inactive: optional boolean`

  Include inactive instruments. Default false.

- `--include-restricted: optional boolean`

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

- `--page-size: optional number`

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

- `--page-token: optional string`

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

### Returns

- `V1InstrumentSearchInstrumentsResponse: BaseResponse`

  - `data: array of InstrumentCore`

    - `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.

    - `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

### Example

```cli
clear-street v1:instruments search-instruments \
  --api-key 'My API Key' \
  --q q
```

#### Response

```json
{
  "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": "..."
  }
}
```