Insights API

Overview

The Insights API provides access to AI-generated signals for individual stocks and the overall market. Each insight represents a specific observed pattern: insider cluster buying, institutional position changes, sentiment baseline deviations, volume anomalies, short interest spikes, and more. New signal types (earnings catalysts, options flow, sector rotation) are added as new data sources come online.

Use cases:

• Scan for high-urgency signals across a watchlist to prioritize research
• Filter by insight type to build specialized monitors (e.g., only insider_buy_signal or volume_spike_anomaly)
• Combine insight confidence scores with your own models for signal weighting
• Cross-reference AI signals with insider trading and institutional flow data

Insight fields:

• insightType: Category of the signal (e.g., insider_buy_signal, institutional_position_change, volume_spike_anomaly)
• insightText: The full AI-generated description of the signal
• confidence: Model confidence score (0.0-1.0)
• urgency: Signal priority: low, medium, or high
• generatedAt: When this insight was generated (epoch seconds)
• docRefs: Source documents the insight was derived from (optional)

Sorting: varies by endpoint. The per-stock endpoint (/stock/{ticker}) and the personalized feed (/user) are ranked by importance (a blend of impact, confidence, and recency) so fresh, meaningful signals lead. /stock/{ticker}/range and /market are sorted by urgency (high first) then confidence (descending). /latest is sorted newest first.

Access: PRO subscription required for full data. Free and unauthenticated users receive a preview with the top N insights wrapped in {isPreview: true, data: [...]}.

---

GET /stock/{ticker}

Returns AI-generated insights for a specific stock, ranked by importance (impact, confidence, and recency): data[0] is the top insight.

Authentication: PRO required. Free users receive the top 3 insights in full, plus metadata for the rest.

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol (e.g., AAPL)
urgency	string	No	-	Filter by urgency: low, medium, or high
insightType	string	No	-	Filter by insight type (e.g., insider_buy_signal)

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/insights/stock/AAPL"

# Filter by urgency
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/insights/stock/AAPL?urgency=high"

from sentisense import SentiSenseClient

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")

# All insights for AAPL
insights = client.get_stock_insights("AAPL")
for i in insights:
    print(f"[{i['urgency'].upper()}] {i['insightType']}: {i['insightText'][:80]}")

# High-urgency only
alerts = client.get_stock_insights("NVDA", urgency="high")

Response Schema:

All tiers return a unified wrapper: {isPreview: bool, previewReason: string|null, data: [...]}. Access insights via response.data.

Insight object fields:

Field	Type	Description
insightId	string	Stable content-hash ID for dedup and feedback
insightType	string	Signal type key (e.g., insider_buy_signal, volume_spike_anomaly)
category	string	SENTIMENT, TRENDING, TECHNICAL, FUNDAMENTAL, or PERSONALIZED
insightText	string	The insight description
confidence	float	Confidence score (0.0-1.0)
urgency	string	low, medium, or high
generatedAt	long	Epoch seconds when this insight was generated
docRefs	array	Source document references: [{url, type}] (may be null)

Example Response:

{
  "isPreview": false,
  "previewReason": null,
  "data": [
    {
      "insightId": "insider_buy_signal_AAPL_a1b2c3d4",
      "insightType": "insider_buy_signal",
      "category": "FUNDAMENTAL",
      "insightText": "5 insiders at Apple Inc (AAPL) bought shares in the past 30 days: 12 trades totaling $45.2M",
      "confidence": 0.85,
      "urgency": "high",
      "generatedAt": 1742500800,
      "docRefs": null
    },
    {
      "insightId": "institutional_position_change_AAPL_e5f6g7h8",
      "insightType": "institutional_position_change",
      "category": "FUNDAMENTAL",
      "insightText": "12 institutions increased positions in AAPL last quarter, adding 8.3M shares net",
      "confidence": 0.85,
      "urgency": "medium",
      "generatedAt": 1742497200,
      "docRefs": [{"url": "https://...", "type": "News"}]
    }
  ]
}

FREE tier: same shape with isPreview: true and data truncated to top 3.

---

GET /stock/{ticker}/range

Returns AI insights for a specific stock within a date range, sorted by urgency and confidence.

Authentication: PRO required. Free users receive the top 3 insights.

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol
startDate	string	Yes	-	ISO date (YYYY-MM-DD), inclusive
endDate	string	Yes	-	ISO date (YYYY-MM-DD), inclusive. Must be on or after startDate
urgency	string	No	-	Filter by urgency: low, medium, or high
insightType	string	No	-	Filter by insight type

Both bounds are matched against each insight's generatedAt, and the calendar days are resolved in US Eastern (America/New_York), so the window rolls over at midnight Eastern rather than at your local midnight.

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/insights/stock/AAPL/range?startDate=2026-04-01&endDate=2026-04-30"

Response shape matches GET /stock/{ticker} (see above). Returns 400 invalid_parameter when startDate is after endDate.

---

GET /market

Returns AI-generated insights about overall market conditions, sorted by urgency and confidence. Includes market-wide aggregations (insider buying trends, institutional rotation) and top high-urgency stock signals.

Authentication: PRO required. Free users receive the top 5 insights in full, plus metadata for the rest.

Parameters: None

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/insights/market"

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
market = client.get_market_insights()

# PRO: flat list
for i in market:
    print(f"[{i['urgency'].upper()}] {i['insightText'][:100]}")

Response Schema: Same insight object fields as /stock/{ticker} above.

Example Response:

{
  "isPreview": false,
  "previewReason": null,
  "data": [
    {
      "insightId": "market_insider_trend_global",
      "insightType": "market_insider_trend",
      "category": "FUNDAMENTAL",
      "insightText": "Insider buying activity across 23 stocks in the past 14 days. Total buys: $128.5M across 15 stocks. Total sells: $45.2M across 8 stocks. Top insider buying: NVDA, AAPL, MSFT, AMD, AVGO",
      "confidence": 0.85,
      "urgency": "high",
      "generatedAt": 1742500800,
      "docRefs": null
    }
  ]
}

FREE tier: same wrapper with isPreview: true and data truncated to top 5.

---

GET /latest

Returns the latest AI insights across all tracked stocks, newest first.

Authentication: PRO required. Free users receive the top 5 insights.

Parameters:

Parameter	Type	Required	Default	Description
limit	int	No	50	Max number of insights to return. Clamped to the range 1 to 200
urgency	string	No	-	Filter by urgency: low, medium, or high

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/insights/latest?limit=10"

Response shape matches GET /stock/{ticker} (the same {isPreview, previewReason, data} envelope with the same insight objects).

---

GET /user

Returns personalized insights for the authenticated user, biased toward their watchlist when available. For users without a watchlist, returns market-level insights.

Authentication: API key required. Returns 401 if no credentials are presented.

Parameters:

Parameter	Type	Required	Default	Description
limit	int	No	20	Max number of insights to return. Clamped to 1 to 100
category	string	No	-	Filter by insight category: SENTIMENT, TRENDING, TECHNICAL, FUNDAMENTAL, or PERSONALIZED

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/insights/user?limit=10&category=FUNDAMENTAL"

Response wrapper is {isPreview: false, previewReason: null, data: [...]} since this endpoint is auth-required and returns full data to its caller. Insight objects match the schema in GET /stock/{ticker}.

---

GET /stock/{ticker}/types

Returns the list of insight types that have data available for a specific stock. Use this to discover what kinds of signals exist before calling the main endpoint with an insightType filter. Every listed type has at least one currently servable insight: types whose insights have all expired drop off the list, so filtering the main endpoint by a returned type always yields results.

Authentication: API key required.

Parameters:

Parameter	Type	Required	Description
ticker	path	Yes	Stock ticker symbol (e.g., AAPL)

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/insights/stock/AAPL/types"

types = client.get_insight_types("AAPL")
print(types)  # e.g., ["insider_buy_signal", "institutional_position_change", "volume_spike_anomaly"]

Response Schema: Array of strings.

Example Response:

["insider_buy_signal", "institutional_position_change", "volume_spike_anomaly", "short_interest_spike"]

Available insight types (new types are added as data sources expand). This list is the complete
public catalog; a type appearing here does not guarantee it currently has data for every ticker.
GET /stock/{ticker}/types can additionally return legacy editorial keys that are not in this
table, carried by manually authored insights; they behave like any other type when passed as an
insightType filter.

Type	Category	Description
market_sentiment_pulse	Sentiment	Overall market sentiment pulse, computed in real time (market endpoint only)
ai_sentiment_shift	Sentiment	AI-detected shift in sentiment based on document analysis
etf_sentiment_divergence_widening	Sentiment	Gap between an ETF's own sentiment and its holdings-weighted sentiment widened beyond baseline
market_volume_spike	Technical	Market-wide trading volume spike detection (market endpoint only)
sentisense_score_3std_deviation	Technical	SentiSense Score moved 3+ standard deviations from its historical baseline
sentiment_3std_deviation	Technical	Sentiment metric moved 3+ standard deviations from its historical baseline
mentions_3std_deviation	Technical	Social mention volume moved 3+ standard deviations from its historical baseline
volume_spike_anomaly	Technical	Abnormally high trading volume detected
volume_drop_anomaly	Technical	Abnormally low trading volume detected
price_sentiment_divergence	Technical	Price movement diverges from sentiment signals
momentum_divergence	Technical	Momentum divergence between price and volume signals
volume_breakout_signal	Technical	Volume breakout with limited accompanying price movement
volatility_spike	Technical	High volatility spike with elevated volume
liquidity_analysis	Technical	Liquidity analysis flagging excellent or poor trading conditions
liquidity_warning	Technical	Warning for unusually low trading liquidity
market_correlation	Technical	Strong correlation between a stock and broader market sentiment movements
ai_technical_signal	Technical	AI-detected technical chart signal
ai_options_activity	Technical	AI-detected options activity pattern
etf_holdings_weighted_score_3std_deviation	Technical	3-sigma baseline deviation on an ETF's holdings-weighted SentiSense Score
options_pc_ratio_extreme	Technical	Put/call volume ratio at an extreme percentile of the ticker's own trailing 1-year range
options_iv_rank_spike	Technical	At-the-money implied volatility at an IV rank of 90 or higher within the trailing 1-year range
options_skew_extreme	Technical	25-delta options skew at an extreme percentile of the trailing 1-year range
options_oi_wall_concentration	Technical	A single strike concentrates an outsized share of one side's open interest
trending_stock_bullish	Trending	Stock showing a bullish trending pattern
trending_stock_bearish	Trending	Stock showing a bearish trending pattern
youtube_mention_spike	Trending	A stock's YouTube mention volume surged well above its own recent baseline
earnings_upcoming	Fundamental	Upcoming earnings announcement for a stock
report_available	Fundamental	A SentiSense Intelligence report is available for a stock or industry
market_insider_trend	Fundamental	Aggregate insider buying or selling trend across multiple stocks (market endpoint only)
market_institutional_rotation	Fundamental	Aggregate institutional flow pattern across sectors or the market (market endpoint only)
institutional_flow	Fundamental	Institutional flow pattern detected from volume and price analysis
insider_buy_signal	Fundamental	Insider cluster buys or large individual purchases from SEC Form 4 filings
insider_cluster_buy	Fundamental	3 or more distinct insiders reported qualifying open-market purchases in the configured window
insider_whale_buy	Fundamental	A qualifying open-market insider purchase was large relative to reported holdings or trailing insider activity
insider_sell_signal	Fundamental	Significant insider selling activity from SEC Form 4 filings
institutional_position_change	Fundamental	Notable institutional inflows, outflows, or activist positions from 13F filings
stock_earnings_reaction_pattern	Fundamental	A company that just reported has a run or a strong skew in how the market traded its recent earnings sessions
analyst_rating_acceleration	Fundamental	3 or more analyst upgrade or downgrade actions on a stock within 7 days
analyst_target_divergence	Fundamental	Analyst mean price target diverges materially (25%+) from the current price
analyst_called_it	Fundamental	A stock made a large move and at least one covering firm had already revised its price target in that direction, with a count of how many firms moved the other way or did not move; per-call detail at /api/v1/analyst/{ticker}/called-it
analyst_reaction	Fundamental	How many of a stock's covering firms moved in the five trading sessions after an earnings print, what each group did, and how many have not published since
company_kpi_trend	Fundamental	A curated company KPI moved favorably or unfavorably between reporting periods
short_interest_spike	Fundamental	Short interest increased more than 20% between consecutive FINRA reports
short_volume_ratio_spike	Fundamental	Daily short volume ratio is abnormally high relative to its 20-day average
politician_buy_cluster	Fundamental	3 or more members of Congress purchased the same stock within 30 days
politician_sell_cluster	Fundamental	3 or more members of Congress sold the same stock within 30 days
politician_notable_trade	Fundamental	A high-profile politician made a notable trade recently
sec_filing_risk_change	Fundamental	A company's latest 10-K or 10-Q materially rewrote a tracked section, Risk Factors first, versus its prior filing
ai_news_catalyst	Fundamental	AI-identified news catalyst or event
ai_risk_assessment	Fundamental	AI-generated risk assessment
etf_insider_flow_sign_flip	Fundamental	An ETF's holdings-weighted 30-day net insider dollar flow flipped sign versus the previous reading
etf_weighted_upside_threshold_cross	Fundamental	An ETF's holdings-weighted analyst upside crossed a configured threshold versus the previous reading
watchlist_significant_move	Personalized	Significant movement in a stock on the user's watchlist

Insider-purchase insights cover open-market purchases only. Transactions under a 10b5-1 plan,
non-purchase transaction codes, and filings older than seven days are excluded. At most one insight
is emitted per stock per purchase episode and at most five across the market per New York day.