Search Instruments

InstrumentSearchInstrumentsResponse v1().instruments().searchInstruments(, )

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

InstrumentSearchInstrumentsParams params

String q

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.

Optional<String> assetClass

Optional<String> country

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

Optional<String> currency

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

Optional<Boolean> includeInactive

Include inactive instruments. Default false.

Optional<Boolean> includePtp

Include publicly traded partnership (PTP) instruments. Default true (penalized in ranking).

Optional<Long> pageSize

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

formatint64

maximum100

minimum1

Optional<String> pageToken

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:

List<InstrumentCore> data

String id

Unique instrument identifier (UUID)

formatuuid

String countryOfIssue

The ISO country code of the instrument’s issue

String currency

The ISO currency code in which the instrument is traded

boolean easyToBorrow

Indicates if the instrument is classified as Easy-To-Borrow

boolean isFractionable

Indicates if the instrument supports fractional-quantity orders

boolean isLiquidationOnly

Indicates if the instrument is liquidation only and cannot be bought

boolean isMarginable

Indicates if the instrument is marginable

boolean isPtp

Indicates if the instrument is a publicly traded partnership (PTP). PTP sales are subject to a 10% withholding tax for non-US tax residents.

boolean isShortProhibited

Indicates if short selling is prohibited for the instrument

boolean isThresholdSecurity

Indicates if the instrument is on the Regulation SHO Threshold Security List

boolean isTradable

Indicates if the instrument is tradable

String symbol

The trading symbol for the instrument

String venue

The MIC code of the primary listing venue

Optional<String> adv

Average daily share volume from the security definition. When a null/undefined value is observed, it indicates that there is no available data.

DeprecatedOptional<LocalDate> expiry

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

formatdate

Optional<SecurityType> instrumentType

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

One of the following:

COMMON_STOCK("COMMON_STOCK")

OPTION("OPTION")

CASH("CASH")

Optional<String> longMarginRate

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.

Optional<String> name

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

Optional<String> notionalAdv

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.

Optional<String> previousClose

Last close price from the security definition. When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> shortMarginRate

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.

DeprecatedOptional<String> strikePrice

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

Search Instruments

package com.clearstreet.api.example;

import com.clearstreet.api.client.ClearStreetClient;
import com.clearstreet.api.client.okhttp.ClearStreetOkHttpClient;
import com.clearstreet.api.models.v1.instruments.InstrumentSearchInstrumentsParams;
import com.clearstreet.api.models.v1.instruments.InstrumentSearchInstrumentsResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        ClearStreetClient client = ClearStreetOkHttpClient.builder()
            .fromEnv()
            .apiKey("My API Key")
            .build();

        InstrumentSearchInstrumentsParams params = InstrumentSearchInstrumentsParams.builder()
            .q("q")
            .build();
        InstrumentSearchInstrumentsResponse response = client.v1().instruments().searchInstruments(params);
    }
}

{
  "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"
  }
}