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_anomaly_high)
• 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_anomaly_high)
• 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: Insights are sorted by urgency (high first) then confidence (descending), so the most actionable signals appear 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, sorted by urgency and confidence.

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

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_MARKET_x9y0z1w2",
      "insightType": "market_insider_trend",
      "category": "FUNDAMENTAL",
      "insightText": "Insider buying activity across 15 stocks in the past 14 days. Total buys: $128.5M across 15 stocks. Total sells: $45.2M across 8 stocks.",
      "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 and portfolio 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 (e.g. SENTIMENT, INSIDER, INSTITUTIONAL)

Example Request:

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

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.

Authentication: None required.

Parameters:

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

Example Request:

curl "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_anomaly_high"]

Response Schema: Array of strings.

Example Response:

["insider_buy_signal", "institutional_position_change", "volume_anomaly_high", "short_interest_spike"]

Available insight types (new types are added as data sources expand):

Type	Category	Description
insider_buy_signal	Fundamental	Insider cluster buys or large individual purchases from SEC Form 4
insider_sell_signal	Fundamental	Significant insider selling activity
institutional_position_change	Fundamental	Notable institutional inflows, outflows, or activist positions from 13F
volume_anomaly_high	Technical	Abnormally high trading volume detected
sentisense_score_baseline_deviation	Sentiment	SentiSense Score deviated 3+ standard deviations from baseline
sentiment_baseline_deviation	Sentiment	Social sentiment shifted significantly from baseline
mentions_baseline_deviation	Sentiment	Social mention volume spiked above baseline
short_interest_spike	Fundamental	Short interest increased >20% between reports
market_insider_trend	Fundamental	Market-wide insider buying/selling trend (market endpoint only)
market_institutional_rotation	Fundamental	Cross-sector institutional rotation pattern (market endpoint only)