// endpoints

Search

Arbitrary multi-field filtering across all assets

GET https://api.tickerdb.com/v1/search

Search across all assets using arbitrary filter combinations. Build complex queries like "all oversold tech stocks with high volume" or "crypto in strong uptrend with a squeeze active." Filters are passed as a JSON array.

Request And Response Names

For /v1/search, canonical request fields, fields[], sort_by, and result keys all use the same flat names returned by /v1/schema/fields, such as momentum_rsi_zone, trend_direction, pattern_bull_flag, ma50, and fundamentals_valuation_zone.

Compatibility Aliases

Schema returns canonical flat names only. For example, insider_activity_zone is accepted as a compatibility alias, but the canonical search/schema field is insider_zone. Search still accepts a few older aliases for backwards compatibility, such as rsi_zone → momentum_rsi_zone and trend.direction → trend_direction. New clients and generated agents should use the canonical flat names everywhere.

Result Nullability

Search returns computed snapshot fields for the asset/date you queried. The response keys use the same canonical flat snake_case names you send in filters, fields, and sort_by. A documented field can still be null for a given row when that classification or source dataset is unavailable for that asset/date. That most commonly affects some fundamentals and insider fields, and may also appear on older rows before a newer classification has been backfilled.

Weekly Stage Analysis

trend_stage is a conservative 40-week stage-analysis field. Use it with timeframe=weekly; daily rows intentionally return null instead of a noisy daily approximation.

Derived Insider Fields

Public search responses keep insider data derived-only. Use insider_zone, insider_net_direction, and insider_quarter rather than raw transaction counts or share totals.

Tier Access

Starter Up to 1 filter, 25 results, 30-day history.
Plus Up to 3 filters, 100 results, 2-year history.
Pro Up to 10 filters, 500 results, 5+ years of history. Business includes up to 10 filters per seat.

Parameters

Parameter	Type	Required	Description
`filters`	`JSON array`	Yes	Array of filter objects. Each filter has `field`, `op`, and `value`. Prefer canonical flat field names from `/v1/schema/fields`.
`date`	`string`	No	Query a historical date (`YYYY-MM-DD`). Defaults to latest. Tier-gated depth.
`timeframe`	`string`	No	`daily` (default) or `weekly`
`sort_by`	`string`	No	Canonical field name to sort results by. Use `market_cap` for largest-company rankings.
`sort_direction`	`string`	No	`asc` or `desc` (default: `desc`)
`limit`	`integer`	No	Max results to return. Tier-gated maximum.
`fields`	`JSON array or string`	No	Columns to return. JSON array (e.g. `["ticker","sector","market_cap","momentum_rsi_zone"]`) or comma-separated (e.g. `ticker,sector,market_cap,momentum_rsi_zone`). Use `["*"]` for all fields. Omit for a default core subset. `ticker` is always included. Invalid fields return an error pointing to `/v1/schema/fields`.

Filter Object

Each filter in the filters array has three fields:

Field	Type	Description
`field`	`string`	The field to filter on (e.g. `momentum_rsi_zone`, `sector`, `asset_class`). Use `/v1/schema/fields` to discover all queryable fields.
`op`	`string`	Comparison operator
`value`	`any`	Value to compare against. Type depends on the field.

Operators

Operator	Description	Example
`eq`	Equal to	`{"field": "momentum_rsi_zone", "op": "eq", "value": "oversold"}`
`neq`	Not equal to	`{"field": "asset_class", "op": "neq", "value": "crypto"}`
`in`	In list	`{"field": "momentum_rsi_zone", "op": "in", "value": ["oversold", "deep_oversold"]}`
`gt`	Greater than	`{"field": "volume_percentile", "op": "gt", "value": 90}`
`gte`	Greater than or equal	`{"field": "trend_duration_days", "op": "gte", "value": 10}`
`lt`	Less than	`{"field": "extremes_condition_percentile", "op": "lt", "value": 10}`
`lte`	Less than or equal	`{"field": "volatility_squeeze_days", "op": "lte", "value": 5}`

Examples

Find oversold stocks

curl

curl -G "https://api.tickerdb.com/v1/search" \
  --data-urlencode 'filters=[{"field":"momentum_rsi_zone","op":"eq","value":"oversold"}]' \
  -H "Authorization: Bearer YOUR_API_KEY"

Oversold tech stocks with high volume

curl

curl -G "https://api.tickerdb.com/v1/search" \
  --data-urlencode 'filters=[{"field":"momentum_rsi_zone","op":"in","value":["oversold","deep_oversold"]},{"field":"sector","op":"eq","value":"Technology"},{"field":"volume_ratio_band","op":"in","value":["high","extremely_high"]}]' \
  -H "Authorization: Bearer YOUR_API_KEY"

Crypto in strong uptrend with squeeze

curl

curl -G "https://api.tickerdb.com/v1/search" \
  --data-urlencode 'filters=[{"field":"asset_class","op":"eq","value":"crypto"},{"field":"trend_direction","op":"eq","value":"strong_uptrend"},{"field":"volatility_squeeze_active","op":"eq","value":true}]' \
  -H "Authorization: Bearer YOUR_API_KEY"

Return only specific fields (reduces token usage)

curl

curl -G "https://api.tickerdb.com/v1/search" \
  --data-urlencode 'filters=[{"field":"momentum_rsi_zone","op":"eq","value":"oversold"}]' \
  --data-urlencode 'fields=["ticker","sector","momentum_rsi_zone"]' \
  -H "Authorization: Bearer YOUR_API_KEY"

Sort by valuation percentile (cheapest first)

curl

curl -G "https://api.tickerdb.com/v1/search" \
  --data-urlencode 'filters=[{"field":"fundamentals_valuation_zone","op":"in","value":["deep_value","undervalued"]}]' \
  --data-urlencode 'sort_by=fundamentals_valuation_percentile' \
  --data-urlencode 'sort_direction=asc' \
  -H "Authorization: Bearer YOUR_API_KEY"

Top 5 stocks by historical market cap

Filter to stocks, request market_cap, and sort descending for largest-company rankings on a point-in-time snapshot.

curl

curl -G "https://api.tickerdb.com/v1/search" \
  --data-urlencode 'filters=[{"field":"asset_class","op":"eq","value":"stock"}]' \
  --data-urlencode 'date=2026-06-15' \
  --data-urlencode 'fields=["ticker","market_cap","market_cap_tier"]' \
  --data-urlencode 'sort_by=market_cap' \
  --data-urlencode 'sort_direction=desc' \
  --data-urlencode 'limit=5' \
  -H "Authorization: Bearer YOUR_API_KEY"

Weekly stage 2 near the 40w MA with elevated volume

curl

curl -G "https://api.tickerdb.com/v1/search" \
  --data-urlencode 'timeframe=weekly' \
  --data-urlencode 'filters=[{"field":"trend_stage","op":"eq","value":"stage_2_growth"},{"field":"trend_distance_ma40","op":"in","value":["touching","proximity_above"]},{"field":"volume_ratio_band","op":"in","value":["above_average","high","extremely_high"]}]' \
  --data-urlencode 'fields=["ticker","sector","trend_stage","ma40","trend_distance_ma40","volume_ratio_band","volume_percentile"]' \
  -H "Authorization: Bearer YOUR_API_KEY"

Bull flag setups in uptrends

curl

curl -G "https://api.tickerdb.com/v1/search" \
  --data-urlencode 'filters=[{"field":"pattern_bull_flag","op":"in","value":["immature","mature"]},{"field":"trend_direction","op":"in","value":["uptrend","strong_uptrend"]}]' \
  --data-urlencode 'fields=["ticker","sector","trend_direction","pattern_bull_flag","pattern_bear_flag","volume_ratio_band"]' \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Field	Type	Description
`results`	`array`	Array of matching assets with their current field values. Individual columns may be `null` when a source classification is unavailable for that row.
`timeframe`	`string`	The timeframe queried
`date`	`string \| null`	The resolved snapshot date used for the query
`fields`	`array`	The canonical field names included in each result
`filter_count`	`integer`	Number of filters applied to the query
`result_count`	`integer`	Number of results returned

Example Response

JSON

{
  "timeframe": "daily",
  "date": "2026-04-04",
  "fields": ["ticker", "asset_class", "sector", "momentum_rsi_zone", "trend_direction", "pattern_bull_flag", "pattern_bear_flag", "volatility_regime", "fundamentals_valuation_zone"],
  "filter_count": 2,
  "result_count": 2,
  "results": [
    {
      "ticker": "AAPL",
      "asset_class": "stock",
      "sector": "Technology",
      "momentum_rsi_zone": "oversold",
      "trend_direction": "downtrend",
      "pattern_bull_flag": "no_setup",
      "pattern_bear_flag": "immature",
      "volatility_regime": "high",
      "fundamentals_valuation_zone": "undervalued"
    },
    {
      "ticker": "MSFT",
      "asset_class": "stock",
      "sector": "Technology",
      "momentum_rsi_zone": "oversold",
      "trend_direction": "downtrend",
      "pattern_bull_flag": "no_setup",
      "pattern_bear_flag": "mature",
      "volatility_regime": "above_normal",
      "fundamentals_valuation_zone": "fair_value"
    }
  ]
}

Credit Cost

Each search request costs 1 credit.