Search Instruments

$ clst 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, 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.

ParametersExpand Collapse

--q: string

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

--asset-class: optional string

--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-ptp: optional boolean

Include publicly traded partnership (PTP) 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.

ReturnsExpand Collapse

V1InstrumentSearchInstrumentsResponse: BaseResponse { metadata, error }

data: array of InstrumentCore { id, country_of_issue, currency, 19 more }

id: string

Unique 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_fractionable: boolean

Indicates if the instrument supports fractional-quantity orders

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_ptp: boolean

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

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. When a null/undefined value is observed, it indicates that there is no available data.

Deprecatedexpiry: optional string

Deprecated. Always null. When a null/undefined value is observed, it indicates it does not apply.

instrument_type: optional "COMMON_STOCK" or "OPTION" or "CASH"

The type of security (e.g., Common Stock, ETF) When a null/undefined value is observed, it indicates that there is no available data.

"COMMON_STOCK"

"OPTION"

"CASH"

long_margin_rate: optional string

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: optional string

The full name of the instrument or its issuer When a null/undefined value is observed, it indicates that there is no available data.

notional_adv: optional string

Notional average daily volume (ADV multiplied by previous close price). When a null/undefined value is observed, it indicates that there is no available data.

previous_close: optional string

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: optional string

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.

Deprecatedstrike_price: optional string

Deprecated. Always null. When a null/undefined value is observed, it indicates it does not apply.

Search Instruments

clst v1:instruments search-instruments \
  --api-key 'My API Key' \
  --q q

{
  "data": [
    {
      "country_of_issue": "US",
      "currency": "USD",
      "easy_to_borrow": true,
      "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b",
      "instrument_type": "COMMON_STOCK",
      "is_fractionable": false,
      "is_liquidation_only": false,
      "is_marginable": true,
      "is_ptp": false,
      "is_short_prohibited": false,
      "is_threshold_security": false,
      "is_tradable": true,
      "name": "Apple Inc.",
      "symbol": "AAPL",
      "venue": "XNMS"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "6c7d8e9f-0a1b-2c3d-4e5f-6a7b8c9d0e1f"
  }
}

{
  "data": [
    {
      "country_of_issue": "US",
      "currency": "USD",
      "easy_to_borrow": true,
      "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b",
      "instrument_type": "COMMON_STOCK",
      "is_fractionable": false,
      "is_liquidation_only": false,
      "is_marginable": true,
      "is_ptp": 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": [
    {
      "country_of_issue": "US",
      "currency": "USD",
      "easy_to_borrow": true,
      "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b",
      "instrument_type": "COMMON_STOCK",
      "is_fractionable": false,
      "is_liquidation_only": false,
      "is_marginable": true,
      "is_ptp": false,
      "is_short_prohibited": false,
      "is_threshold_security": false,
      "is_tradable": true,
      "name": "Apple Inc.",
      "symbol": "AAPL",
      "venue": "XNMS"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "6c7d8e9f-0a1b-2c3d-4e5f-6a7b8c9d0e1f"
  }
}

{
  "data": [
    {
      "country_of_issue": "US",
      "currency": "USD",
      "easy_to_borrow": true,
      "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b",
      "instrument_type": "COMMON_STOCK",
      "is_fractionable": false,
      "is_liquidation_only": false,
      "is_marginable": true,
      "is_ptp": 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"
  }
}