// asset_endpoints

Events

GET /v1/events

Search for historical band transition events for a ticker. Every time a categorical band value changes (e.g. RSI moving from oversold to deep_oversold), a transition event is recorded. This endpoint lets you query those events with optional aftermath performance data showing what happened afterward.

Use Cases

"When was AAPL last deep_oversold?"
"How many times has TSLA entered strong_uptrend this year?"
"What happened after NVDA's last overbought reading?"

Parameters

Parameter	Type	Required	Description
`ticker`	string	Yes	Asset ticker symbol (e.g. `AAPL`)
`field`	string	Yes	Band field name (e.g. `rsi_zone`, `trend_direction`). See Bands Reference
`timeframe`	string	No	`daily` (default) or `weekly`
`band`	string	No	Filter to a specific band value (e.g. `deep_oversold`)
`limit`	int	No	Max results (1-100, default 10)
`before`	string	No	Return events before this date (YYYY-MM-DD)
`after`	string	No	Return events after this date (YYYY-MM-DD)
`context_ticker`	string	No	A second ticker to correlate against. Requires `context_field` and `context_band`. Plus/Pro only
`context_field`	string	No	The band field to check on the context ticker (e.g. `trend_direction`)
`context_band`	string	No	Only return events where the context ticker was in this band on the event date

Tier Access

Feature	Free	Plus	Pro
Technical fields	Yes	Yes	Yes
Basic fundamental fields	-	Yes	Yes
Advanced fundamental fields	-	-	Yes
Aftermath data	-	Yes	Yes
Cross-asset correlation	-	Yes	Yes
Date range	90 days	2 years	5 years

Supported Fields

Technical (Free tier)

rsi_zone, trend_direction, ma_alignment, volume_ratio_band, accumulation_state, volatility_regime, macd_state, support_status, resistance_status

Basic Fundamentals (Plus tier)

valuation_zone, growth_zone, earnings_proximity, analyst_consensus

Advanced Fundamentals (Pro tier)

pe_vs_historical, pe_vs_sector, revenue_growth_direction, eps_growth_direction, earnings_surprise, analyst_consensus_direction, insider_activity_zone, net_direction

Aftermath

Aftermath shows the cumulative return performance at fixed lookahead windows after the event date. Each window value is a per-ticker percentile-based band:

Band	Percentile Range
`sharp_decline`	Bottom 5%
`moderate_decline`	5th-20th percentile
`slight_decline`	20th-40th percentile
`flat`	40th-60th percentile
`slight_gain`	60th-80th percentile
`moderate_gain`	80th-95th percentile
`sharp_gain`	Top 5%

Daily windows: 5d, 10d, 20d, 50d, 100d

Weekly windows: 2w, 4w, 8w, 12w, 16w

Aftermath values are null for recent events where the lookahead window hasn't elapsed yet. They fill in progressively as time passes.

Cross-Asset Correlation

Filter events to only those where a second ticker was in a specific band on the same date. All three context_* parameters must be provided together. The context ticker's band is determined by its most recent transition on or before the event date.

Use Cases

"Show AAPL deep_oversold events, but only when SPY trend was downtrend" (broad selloff vs isolated weakness)
"When was NVDA in strong_uptrend while SMH was in downtrend?" (relative strength divergence)
"TSLA overbought events where QQQ was also overbought" (overheated market)

Cross-asset correlation costs 2 credits per request (1 per ticker queried). Available on Plus and Pro plans.

Example Request

curl

curl "https://api.tickerapi.ai/v1/events?ticker=AAPL&field=rsi_zone&band=deep_oversold&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

With Cross-Asset Correlation

curl

curl "https://api.tickerapi.ai/v1/events?ticker=AAPL&field=rsi_zone&band=deep_oversold&context_ticker=SPY&context_field=trend_direction&context_band=downtrend&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

JSON

{
  "ticker": "AAPL",
  "field": "rsi_zone",
  "timeframe": "daily",
  "events": [
    {
      "date": "2026-03-15",
      "band": "deep_oversold",
      "prev_band": "oversold",
      "stability_at_entry": "fresh",
      "flips_recent_at_entry": 3,
      "flips_lookback": "30d",
      "duration_days": null,
      "aftermath": {
        "5d": { "performance": "moderate_gain" },
        "10d": { "performance": "sharp_gain" },
        "20d": null,
        "50d": null,
        "100d": null
      }
    },
    {
      "date": "2025-12-03",
      "band": "deep_oversold",
      "prev_band": "oversold",
      "stability_at_entry": "holding",
      "flips_recent_at_entry": 2,
      "flips_lookback": "30d",
      "duration_days": 3,
      "aftermath": {
        "5d": { "performance": "sharp_gain" },
        "10d": { "performance": "moderate_gain" },
        "20d": { "performance": "sharp_gain" },
        "50d": { "performance": "moderate_gain" },
        "100d": { "performance": "slight_gain" }
      }
    }
  ],
  "total_occurrences": 7,
  "query_range": "5y"
}

Response Fields

Field	Type	Description
`ticker`	string	The queried ticker symbol
`field`	string	The queried band field name
`timeframe`	string	`daily` or `weekly`
`events[].date`	string	Date the transition occurred (YYYY-MM-DD)
`events[].band`	string	The band value entered on this date
`events[].prev_band`	string	The band value before the transition
`events[].stability_at_entry`	string	Stability of the band at time of entry: `fresh`, `holding`, `established`, or `volatile`. Plus Pro
`events[].flips_recent_at_entry`	int	Number of recent flips at time of entry. Plus Pro
`events[].flips_lookback`	string	Lookback window for flip counting (e.g. `30d`, `12w`). Plus Pro
`events[].duration_days`	int \| null	How long the ticker stayed in this band (daily timeframe). `null` if still active
`events[].duration_weeks`	int \| null	How long the ticker stayed in this band (weekly timeframe). `null` if still active
`events[].aftermath`	object \| null	Cumulative return performance at lookahead windows. `null` for Free tier
`total_occurrences`	int	Total matching events within your tier's date range
`query_range`	string	Your tier's lookback range (`90d`, `2y`, or `5y`)
`context`	object	Present when cross-asset correlation is used. Contains `ticker`, `field`, and `band`

Credit Cost

1 credit per request. When using cross-asset correlation (context_ticker), 2 credits per request.