// 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.

Fundamentals Require Pro

Every fundamentals_* field is Pro-only in filters, selected fields, sorting, wildcard results, and returned rows. Plus receives no fundamental values. Schema remains public for field discovery and marks these definitions with minimum_tier: "pro". The response example below uses Pro fields.

Raw P/E As Of The Snapshot

The canonical field is pe_ratio, and it is Pro-only like every other fundamental. Search uses the latest raw P/E recorded on or before each result's snapshot date, including the week-ending date for weekly results. Negative values are preserved; unavailable values are null.

Value Divergence Model

The Pro-only value_divergence_* fields are populated on verified weekly stock snapshots. Filter on value_divergence_eligible=true, rank with sort_by=value_divergence_score&sort_direction=desc, and request the band and exclusion reason for an explainable result. Daily, ETF, crypto, and not-yet-verified historical rows return null model fields.

Historical Market-Cap Integrity

Explicit weekly requests (timeframe=weekly&date=YYYY-MM-DD) include a weekly_integrity object for the full stock publication, independent of your filters and result limit. Exact large, mega, and ultra_mega tiers qualify for the model. large_or_larger_proven also qualifies when the server can prove the threshold without an exact raw value. below_large_proven is confirmed below the threshold. unknown means the threshold cannot be established; it is excluded individually and is never reinterpreted as small. For all three evidence-only tiers, market_cap is null and the API will not expose a stale sidecar fallback.

Fail-Closed Weekly Publications

Check weekly_integrity.publication_complete before consuming historical model results. It is false when the canonical publication record is absent or stale, an unknown row violates its exclusion contract, a proven-large row is mishandled, or an explicitly incomplete universe violates its all-stock risk-off contract. universe_incomplete=true means the entire week is risk-off; ordinary unknown rows alone do not make the whole week risk-off.

Request And Response Names

pattern_bull_flag_breakout is boolean: filter it with {"field":"pattern_bull_flag_breakout","op":"eq","value":true}. It is true on the breakout candle and the following two daily or weekly candles after a confirmed mature bull flag closes above its buffered consolidation ceiling. pattern_bear_flag_breakdown is the bearish counterpart: filter it with {"field":"pattern_bear_flag_breakdown","op":"eq","value":true}. It is true on the breakdown candle and the following two daily or weekly candles after a confirmed mature bear flag closes below its buffered consolidation floor. 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, pattern_ascending_triangle, ma50, fundamentals_valuation_zone, and fundamentals_free_cash_flow.

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, 3-year history.
Pro Up to 10 filters, 500 results, 7 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_bull_flag_breakout","pattern_bear_flag","pattern_bear_flag_breakdown","pattern_ascending_triangle","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.
`weekly_integrity`	`object`	Present on explicit weekly-date requests. Contains `unknown_market_cap_rows`, `proven_large_rows`, `proven_below_large_rows`, `universe_incomplete`, and `publication_complete` for the full stock publication.
`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_bull_flag_breakout", "pattern_bear_flag", "pattern_bear_flag_breakdown", "pattern_ascending_triangle", "pattern_rising_wedge", "volatility_regime", "fundamentals_valuation_zone", "fundamentals_free_cash_flow"],
  "filter_count": 2,
  "result_count": 2,
  "results": [
    {
      "ticker": "AAPL",
      "asset_class": "stock",
      "sector": "Technology",
      "momentum_rsi_zone": "oversold",
      "trend_direction": "downtrend",
      "pattern_bull_flag": "not_detected",
      "pattern_bull_flag_breakout": false,
      "pattern_bear_flag": "immature",
      "pattern_bear_flag_breakdown": false,
      "pattern_ascending_triangle": "not_detected",
      "pattern_rising_wedge": "invalidated",
      "volatility_regime": "high",
      "fundamentals_valuation_zone": "undervalued",
      "fundamentals_free_cash_flow": "moderate_surplus"
    },
    {
      "ticker": "MSFT",
      "asset_class": "stock",
      "sector": "Technology",
      "momentum_rsi_zone": "oversold",
      "trend_direction": "downtrend",
      "pattern_bull_flag": "not_detected",
      "pattern_bull_flag_breakout": false,
      "pattern_bear_flag": "mature",
      "pattern_bear_flag_breakdown": true,
      "pattern_ascending_triangle": "immature",
      "pattern_rising_wedge": "not_detected",
      "volatility_regime": "above_normal",
      "fundamentals_valuation_zone": "fair_value",
      "fundamentals_free_cash_flow": "high_surplus"
    }
  ]
}

Credit Cost

Each search request costs 1 credit.