Search Instruments

client.V1.Instruments.SearchInstruments(ctx, query) (*V1InstrumentSearchInstrumentsResponse, error)

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

query V1InstrumentSearchInstrumentsParams

Q param.Field[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.

AssetClass param.Field[string]Optional

Country param.Field[string]Optional

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

Currency param.Field[string]Optional

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

IncludeInactive param.Field[bool]Optional

Include inactive instruments. Default false.

IncludeRestricted param.Field[bool]Optional

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

PageSize param.Field[int64]Optional

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

formatint64

maximum100

minimum1

PageToken param.Field[string]Optional

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

formatbyte

ReturnsExpand Collapse

type V1InstrumentSearchInstrumentsResponse struct{…}

Data InstrumentCoreList

ID string

Unique OEMS instrument identifier (UUID)

formatuuid

CountryOfIssue string

The ISO country code of the instrument’s issue

Currency string

The ISO currency code in which the instrument is traded

EasyToBorrow bool

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

IsLiquidationOnly bool

Indicates if the instrument is liquidation only and cannot be bought

IsMarginable bool

Indicates if the instrument is marginable

IsRestricted bool

Indicates if the instrument is restricted from trading

IsShortProhibited bool

Indicates if short selling is prohibited for the instrument

IsThresholdSecurity bool

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

IsTradable bool

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 stringOptional

Average daily share volume from the security definition.

Expiry TimeOptional

The expiration date for options instruments

formatdate

InstrumentType SecurityTypeOptional

The type of security (e.g., Common Stock, ETF)

One of the following:

const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"

const SecurityTypePreferredStock SecurityType = "PREFERRED_STOCK"

const SecurityTypeOption SecurityType = "OPTION"

const SecurityTypeCash SecurityType = "CASH"

const SecurityTypeOther SecurityType = "OTHER"

LongMarginRate stringOptional

The percent of a long position’s value you must post as margin

Name stringOptional

The full name of the instrument or its issuer

NotionalAdv stringOptional

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.

PreviousClose stringOptional

Last close price from the security definition.

ShortMarginRate stringOptional

The percent of a short position’s value you must post as margin

StrikePrice stringOptional

The strike price for options instruments

Search Instruments

package main

import (
  "context"
  "fmt"

  "github.com/clear-street/clear-street-go"
  "github.com/clear-street/clear-street-go/option"
)

func main() {
  client := clearstreet.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.V1.Instruments.SearchInstruments(context.TODO(), clearstreet.V1InstrumentSearchInstrumentsParams{
    Q: "q",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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"
  }
}