API Reference

Search for underlying ticker symbols.

Use ticker search with Stock Reference, Stock Snapshots, Options Expirations, Option Chain docs, and Stock and Options Data Join Workflow.

Endpoint

GET /v1/tickers/search

Example Request

curl \
  "https://api.cutemarkets.com/v1/tickers/search/?query=NFLX&limit=8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample Response

{
  "status": "OK",
  "request_id": "cm_7546c8d1ad144068910f4fbf30a01e4f",
  "results": [
    {
      "symbol": "NFLX",
      "name": "NetFlix Inc"
    }
  ]
}

Search behavior

Ticker search is a discovery endpoint, not a market-data endpoint. Use it when a user types a partial company name or symbol and your UI needs a short list of candidate underlyings. After the user selects a symbol, move to the relevant product endpoint: stock reference for company metadata, stock snapshots for current stock state, or options expirations before requesting an option chain.

If the selected route is options, keep the search result separate from Contracts, Options Chain API, and OCC Option Symbol Format. A search hit can identify an underlying, but it does not prove an expiration, strike, or option contract exists.

UI guidance

Keep ticker search results small and explicit. Display symbol and name, then let the selected route determine whether the app needs stocks or options data. Do not treat search results as proof that options exist for a ticker; fetch listed expirations first when the next action is an options chain, options contract list, or expiration-specific scanner.

Autocomplete implementation notes

Ticker search works best as a lightweight autocomplete step. Debounce user input, request a small limit, and show the raw symbol in a monospace style so it is easy to distinguish from the company name. If the user types a symbol-like query, rank exact symbol matches above broader name matches. If the user types a company name fragment, keep the displayed result compact and let the detail endpoint provide richer metadata after selection.

Do not join ticker search directly to a chain request without a selection step. Search results can include symbols that are valid stocks but do not have the options coverage your workflow expects. The safer options sequence is search, select underlying, fetch listed expirations, then request contracts or a chain for one selected date.

Validation and caching

Search results are good candidates for short-lived client caching because users often type, delete, and retype the same prefixes. Cache the query string, result list, and timestamp, but do not cache forever. Ticker status, names, and related metadata can change after corporate actions, listings, delistings, or symbol changes.

For server-side applications, store the selected symbol separately from the displayed company name. The symbol is the routing key for downstream API calls; the name is presentation metadata. If a user reports that the wrong company appeared, the symbol and request id are the fields that make the issue debuggable.

Common mistakes

• Treating a search hit as proof that listed options exist.
• Showing only company names and hiding the exact symbol.
• Requesting a full option chain on every keystroke.
• Reusing a Stocks API key for options endpoints after selection.
• Caching search results so long that renamed or inactive tickers remain visible.

Ticker search implementation notes

Ticker search is a validation step, not a market-data substitute. Use it to normalize user input, distinguish stocks from ETFs or indexes, check active status, and present candidates before requesting snapshots, trades, bars, or option contracts. Store the selected ticker and search result id or metadata used by the UI.

Good ticker search reduces downstream support issues. A user looking for SPY, SPX, SPXW, QQQ, IWM, or TLT may need different market objects. Pair this page with Stock Reference, Option Symbols and Contract Identity, and Expirations so ticker selection leads to the right stock or options workflow.

Additional implementation review

Review the ticker search workflow as a sequence of named data objects, not as a single helper call. The implementation should preserve search query, exchange, asset type, active flag, pagination cursor, canonical ticker, company name, and selected result. Those fields make support tickets, CI fixtures, and replay notebooks easier to compare because every step can point to the exact request and response that created the displayed value.

The main failure mode is that a user can select a display label that looks right but resolves to the wrong security or inactive listing. Before promoting the workflow, run one concrete example through discovery, retrieval, display, logging, and error handling. Keep the resulting artifact beside the code path so future changes can prove they still use the same terminology and the same market-data assumptions.