Watchlist
Save tickers and get latest EOD snapshots for portfolio monitoring
The watchlist is a persistent, per-user list of tickers. Save tickers with POST, remove with DELETE, and fetch the latest available EOD data for all saved tickers with GET. Designed for portfolio monitoring dashboards.
Credits
GET Watchlist costs 1 credit per ticker in your saved watchlist (minimum 1 credit per request). A watchlist with 10 tickers costs 10 credits per GET request. Each ticker returns a full compact snapshot with day-over-day change detection. POST, DELETE, and Changes endpoints cost 1 credit per request.
Tier Limits
Starter up to 10 tickers. Plus up to 50 tickers (200 on Business Plus). Pro up to 100 tickers (500 on Business Pro).
GET — Fetch watchlist with latest EOD data
Returns the latest available EOD snapshot data for all saved tickers. Each item contains trend, momentum, volume, extremes, volatility, support/resistance context, fundamentals (stocks), and notable changes.
Response Fields
Each item in the watchlist array. Fields are tier-gated to match the summary endpoint:
Tier Availability
Starter Core technicals: trend, momentum, extremes, volatility, volume. Plus adds support/resistance context and basic fundamentals. Pro adds advanced fundamentals: earnings surprises, analyst direction shifts, and insider activity.
Band Stability Metadata
Plus Pro Each band field can include a sibling _meta object with stability label, periods_in_current_state, flips_recent, and flips_lookback. Compact watchlist items omit those keys when the corresponding summary metadata is null. Not available on Starter tier. See Band Stability.
Freshness
Each watchlist item includes as_of_date, and the response envelope includes the shared as_of_date when available. Use that date together with data_status to understand exactly which market session your compact snapshots represent. For refresh timing and coverage notes, see Data Quality.
| Field | Type | Description |
|---|---|---|
ticker | string | Asset symbol |
asset_class | string | stock, crypto, or etf |
as_of_date | string | Session date represented by this snapshot |
performance | string | Candle performance vs. asset's own history. See Bands. |
| Trend | ||
trend_direction | string | Current trend |
trend_direction_meta | object | Stability metadata for trend direction. See Band Stability |
trend_duration_days | integer | How many days the current trend has been running |
| Momentum | ||
rsi_zone | string | Current RSI zone |
rsi_zone_meta | object | Stability metadata for RSI zone. See Band Stability |
macd_state | string | expanding_positive, contracting_positive, expanding_negative, or contracting_negative |
macd_state_meta | object | Stability metadata for MACD state. See Band Stability |
divergence_detected | boolean | Whether a price/momentum divergence is active |
divergence_type | string | bullish_divergence or bearish_divergence. null when no divergence |
| Volume | ||
volume_ratio_band | string | Today's volume relative to average |
volume_ratio_band_meta | object | Stability metadata for volume ratio band. See Band Stability |
accumulation_state | string | Institutional flow: accumulation, distribution, or neutral |
accumulation_state_meta | object | Stability metadata for accumulation state. See Band Stability |
climax_detected | boolean | Whether a volume climax event is present |
climax_type | string | buying_climax or selling_climax. null when no climax |
| Extremes | ||
extremes_condition | string | Extreme or normal |
days_in_extreme | integer | Days in extreme. 0 if normal |
condition_rarity | string | How rare current conditions are: extremely_rare to common |
| Volatility | ||
volatility_regime | string | Current volatility regime: low, normal, above_normal, high, or extreme |
volatility_regime_meta | object | Stability metadata for volatility regime. See Band Stability |
squeeze_active | boolean | Bollinger squeeze active |
squeeze_days | integer | Days the current squeeze has been building. 0 if not active |
| Support / Resistance Plus Pro | ||
support_level_distance | string | Proximity to support level |
resistance_level_distance | string | Proximity to resistance level |
| Fundamentals (stocks only) Plus Pro | ||
valuation_zone | string | Current valuation band |
valuation_zone_meta | object | Stability metadata for valuation zone. See Band Stability |
earnings_proximity | string | Next earnings timing |
earnings_proximity_meta | object | Stability metadata for earnings proximity. See Band Stability |
analyst_consensus | string | Analyst recommendation |
analyst_consensus_meta | object | Stability metadata for analyst consensus. See Band Stability |
growth_zone | string | Growth classification based on revenue and earnings trends |
growth_zone_meta | object | Stability metadata for growth zone. See Band Stability |
| Advanced Fundamentals (stocks only) Pro | ||
last_earnings_surprise | string | Most recent earnings result: big_beat, beat, met, missed, or big_miss |
analyst_consensus_direction | string | Direction of consensus shift: upgrading, stable, or downgrading |
insider_activity | string | null | Insider activity zone: heavy_buying, moderate_buying, neutral, moderate_selling, heavy_selling, or no_activity. null when no recent insider data is available. |
insider_net_direction | string | null | Net insider direction: strong_buying, buying, neutral, selling, or strong_selling. null when no recent insider data is available. |
| Changes | ||
notable_changes | array | Day-over-day changes: "entered deep_value", "analyst downgraded", etc. |
Tickers not found return an object with "status": "not_found".
Envelope
| Field | Type | Description |
|---|---|---|
watchlist | array | Array of result objects |
tickers_saved | integer | Total tickers saved |
tickers_found | integer | Tickers with data |
watchlist_limit | integer | Max tickers for your tier |
data_status | string | "eod" |
as_of_date | string | Shared session date for the returned watchlist data, when available |
GET /v1/watchlist
{
"watchlist": [
{
"ticker": "AAPL",
"asset_class": "stock",
"as_of_date": "2026-04-11",
"performance": "slight_gain",
"trend_direction": "uptrend",
"trend_duration_days": 14,
"rsi_zone": "neutral_high",
"macd_state": "contracting_positive",
"divergence_detected": false,
"divergence_type": null,
"volume_ratio_band": "normal",
"accumulation_state": "accumulation",
"climax_detected": false,
"climax_type": null,
"extremes_condition": "normal",
"days_in_extreme": 0,
"condition_rarity": "common",
"squeeze_active": false,
"squeeze_days": 0,
"support_level_distance": "near",
"resistance_level_distance": "very_close",
"valuation_zone": "fair_value",
"earnings_proximity": "this_month",
"last_earnings_surprise": "beat",
"analyst_consensus": "buy",
"analyst_consensus_direction": "upgrading",
"growth_zone": "moderate_growth",
"insider_activity": "moderate_buying",
"insider_net_direction": "buying",
"notable_changes": ["earnings within_days"]
},
{
"ticker": "BTCUSD",
"asset_class": "crypto",
"as_of_date": "2026-04-11",
"performance": "moderate_gain",
"trend_direction": "strong_uptrend",
"trend_duration_days": 21,
"rsi_zone": "overbought",
"macd_state": "expanding_positive",
"divergence_detected": true,
"divergence_type": "bearish_divergence",
"volume_ratio_band": "above_average",
"accumulation_state": "distribution",
"climax_detected": false,
"climax_type": null,
"extremes_condition": "overbought",
"days_in_extreme": 3,
"condition_rarity": "rare",
"squeeze_active": false,
"squeeze_days": 0,
"support_level_distance": "at_level",
"resistance_level_distance": "moderate",
"notable_changes": ["entered overbought", "volume spike"]
}
],
"tickers_saved": 2,
"tickers_found": 2,
"watchlist_limit": 50,
"data_status": "eod",
"as_of_date": "2026-04-11"
}
POST — Add tickers
Add tickers to your saved watchlist. Duplicates are ignored. All tickers are validated against the asset database — only supported tickers can be added. To check whether a ticker is supported, call GET /v1/summary/SYMBOL — a 404 means it is not available.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
tickers | string[] | Yes | Array of ticker symbols to add (must be valid supported tickers) |
Example Request
{
"tickers": ["AAPL", "MSFT", "BTCUSD"]
}
Response
| Field | Type | Description |
|---|---|---|
added | array | Tickers that were added |
already_saved | array | Tickers already in your watchlist |
watchlist_count | integer | Total tickers now saved |
watchlist_limit | integer | Max tickers for your tier |
POST /v1/watchlist
{
"added": ["AAPL", "MSFT", "BTCUSD"],
"already_saved": [],
"watchlist_count": 3,
"watchlist_limit": 50
}
DELETE — Remove tickers
Remove tickers from your saved watchlist.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
tickers | string[] | Yes | Array of ticker symbols to remove |
Example Request
{
"tickers": ["MSFT"]
}
Response
| Field | Type | Description |
|---|---|---|
removed | array | Tickers that were removed |
watchlist_count | integer | Total tickers remaining |
DELETE /v1/watchlist
{
"removed": ["MSFT"],
"watchlist_count": 2
}
GET — State changes
Returns field-level state changes for your saved watchlist tickers since the last pipeline run. For daily timeframe, this shows what changed since yesterday. For weekly, what changed since last week. This returns the same structured diff data that webhooks deliver, but as a pull-based endpoint accessible to all tiers.
All Tiers · 1 credit per request
This endpoint costs 1 credit per request regardless of how many tickers are in your watchlist. Available on all tiers, including Starter. For push-based delivery of the same data, see Webhooks (Plus and Pro only).
Diff Field Naming
The changes object uses short diff-field identifiers. Technical fields stay top-level (rsi_zone, macd_state, extreme_condition), while stock-only fundamental diffs keep a dotted fundamentals.* prefix such as fundamentals.valuation_zone. Schema and Search still use the canonical flat snake_case names like momentum_rsi_zone and fundamentals_valuation_zone.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
timeframe | string | daily | daily (day-over-day) or weekly (week-over-week) |
Tracked Fields
The following fields are tracked for changes:
| Field | Description |
|---|---|
performance | Candle performance band |
rsi_zone | RSI momentum zone |
macd_state | MACD crossover state |
momentum_direction | Overall momentum direction |
divergence_detected | Price/momentum divergence active |
trend_direction | Trend direction |
volume_ratio_band | Volume level |
accumulation_state | Institutional accumulation or distribution |
squeeze_active | Bollinger squeeze state |
extreme_condition | Extreme condition (oversold/overbought) |
breakout_type | Breakout type (if any) |
fundamentals.valuation_zone | Valuation band (stocks only) |
fundamentals.analyst_consensus | Analyst recommendation (stocks only) |
fundamentals.analyst_consensus_direction | Consensus upgrade or downgrade (stocks only) |
fundamentals.earnings_proximity | Next earnings timing (stocks only) |
fundamentals.last_earnings_surprise | Last earnings result (stocks only) |
fundamentals.growth_zone | Growth classification (stocks only) |
Response
| Field | Type | Description |
|---|---|---|
timeframe | string | daily or weekly |
run_date | string | Date of the diff snapshot (YYYY-MM-DD). If the stored diff payload omits it, the API falls back to the most recent known last_changed date. null only when no diff data exists yet. |
changes | object | Map of ticker → array of change objects. Only tickers with changes are included |
ticker_context | object | Per-ticker metadata keyed by ticker. Includes last_changed_date for every saved ticker, even when that ticker had no change in the current response. |
ticker_context.<ticker>.last_changed_date | string | null | Most recent known date when that ticker changed in the stored diff history. null when no prior change has been recorded yet. |
tickers_checked | integer | Number of tickers in your watchlist |
tickers_changed | integer | Number of tickers with at least one change |
Each change object contains:
During initial backfills or the first comparable run for a newly tracked field, from may be null. That means TickerDB has a current value but no prior saved state yet for a clean diff.
| Field | Type | Description |
|---|---|---|
field | string | The field that changed (e.g. "rsi_zone", "fundamentals.valuation_zone") |
from | any | Previous value |
to | any | Current value |
stability | string | Stability of the new band value: fresh, holding, established, or volatile. Present on band field changes. Plus Pro |
periods_in_current_state | integer | Periods in the new band. Plus Pro |
flips_recent | integer | Recent flip count. Plus Pro |
flips_lookback | string | Lookback window for flip counting (e.g. "30d"). Plus Pro |
GET /v1/watchlist/changes
{
"timeframe": "daily",
"run_date": "2026-03-28",
"changes": {
"AAPL": [
{
"field": "rsi_zone",
"from": "neutral",
"to": "oversold",
"stability": "fresh",
"periods_in_current_state": 1,
"flips_recent": 2,
"flips_lookback": "30d"
},
{
"field": "divergence_detected",
"from": false,
"to": true
},
{
"field": "fundamentals.earnings_proximity",
"from": "next_month",
"to": "within_days"
}
],
"BTCUSD": [
{
"field": "squeeze_active",
"from": false,
"to": true
},
{
"field": "accumulation_state",
"from": "neutral",
"to": "accumulation",
"stability": "fresh",
"periods_in_current_state": 1,
"flips_recent": 1,
"flips_lookback": "30d"
}
]
},
"ticker_context": {
"AAPL": {
"last_changed_date": "2026-03-28"
},
"BTCUSD": {
"last_changed_date": "2026-03-28"
}
},
"tickers_checked": 2,
"tickers_changed": 2
}