// asset_endpoints

Watchlist

Save tickers and get live snapshots for portfolio monitoring

The watchlist is a persistent, per-user list of tickers. Save tickers with POST, remove with DELETE, and fetch live 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

Free up to 10 tickers. Plus up to 50 tickers (200 on Commercial). Pro up to 100 tickers (400 on Commercial).

GET — Fetch watchlist with live data

GET https://api.tickerapi.ai/v1/watchlist

Returns live snapshot data for all saved tickers. Each item contains trend, momentum, volume, extremes, volatility, support/resistance levels, fundamentals (stocks), and notable changes.

Parameters

Parameter	Type	Default	Description
`timeframe`	`string`	`daily`	`daily` or `weekly`

Response Fields

Each item in the watchlist array. Fields are tier-gated to match the summary endpoint:

Tier Availability

Free Core technicals: trend, momentum, extremes, volatility, volume. Plus adds support/resistance levels and basic fundamentals. Pro adds advanced fundamentals: earnings surprises, analyst direction shifts, and insider activity.

Band Stability Metadata

Plus Pro Each band field includes a sibling _meta object with stability label, periods_in_current_state, flips_recent, and flips_lookback. Not available on Free tier. See Band Stability.

Field	Type	Description
`ticker`	`string`	Asset symbol
`asset_class`	`string`	`stock`, `crypto`, or `etf`
`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`	MACD crossover state: `bullish_cross`, `bullish`, `bearish_cross`, `bearish`
`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` or `bearish`. `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_price`	`float`	Computed support level price
`support_level_distance`	`string`	Proximity to support level
`resistance_level_price`	`float`	Computed resistance level price
`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: `beat`, `met`, or `missed`
`analyst_consensus_direction`	`string`	Direction of consensus shift: `upgraded`, `downgraded`, or `stable`
`insider_activity`	`string`	Insider trading zone: `buying`, `selling`, `mixed`, or `quiet`
`insider_net_direction`	`string`	Net insider direction: `net_buying`, `net_selling`, or `balanced`
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"`

GET /v1/watchlist

{
  "watchlist": [
    {
      "ticker": "AAPL",
      "asset_class": "stock",
      "performance": "slight_gain",
      "trend_direction": "uptrend",
      "trend_duration_days": 14,
      "rsi_zone": "neutral_high",
      "macd_state": "bullish",
      "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_price": 178.25,
      "support_level_distance": "near",
      "resistance_level_price": 195.80,
      "resistance_level_distance": "very_close",
      "valuation_zone": "fair_value",
      "earnings_proximity": "this_month",
      "last_earnings_surprise": "beat",
      "analyst_consensus": "buy",
      "analyst_consensus_direction": "upgraded",
      "growth_zone": "moderate_growth",
      "insider_activity": "buying",
      "insider_net_direction": "net_buying",
      "notable_changes": ["earnings within_days"]
    },
    {
      "ticker": "BTCUSD",
      "asset_class": "crypto",
      "performance": "moderate_gain",
      "trend_direction": "strong_uptrend",
      "trend_duration_days": 21,
      "rsi_zone": "overbought",
      "macd_state": "bullish",
      "divergence_detected": true,
      "divergence_type": "bearish",
      "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_price": 92150.00,
      "support_level_distance": "at_level",
      "resistance_level_price": 98500.00,
      "resistance_level_distance": "moderate",
      "notable_changes": ["entered overbought", "volume spike"]
    }
  ],
  "tickers_saved": 2,
  "tickers_found": 2,
  "watchlist_limit": 50,
  "data_status": "eod"
}

POST — Add tickers

POST https://api.tickerapi.ai/v1/watchlist

Add tickers to your saved watchlist. Duplicates are ignored. All tickers are validated against the asset database — only supported tickers can be added. Use GET /v1/assets to see available tickers.

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

DELETE https://api.tickerapi.ai/v1/watchlist

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

GET https://api.tickerapi.ai/v1/watchlist/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 Free. For push-based delivery of the same data, see Webhooks (Plus and Pro only).

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 pipeline run (YYYY-MM-DD), or `null` if no data yet
`changes`	`object`	Map of ticker → array of change objects. Only tickers with changes are included
`tickers_checked`	`integer`	Number of tickers in your watchlist
`tickers_changed`	`integer`	Number of tickers with at least one change

Each change object contains:

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"
      }
    ]
  },
  "tickers_checked": 2,
  "tickers_changed": 2
}