Insights API

Overview

The Insights API provides access to AI-generated trading 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: the top N insights in full, plus a locked array of metadata-only entries (type, urgency, timestamp) showing what additional signals exist.

---

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 (PRO, flat array):

Field	Type	Description
insightType	string	Category of signal (e.g., insider_buy_signal, volume_anomaly_high)
insightText	string	Full AI-generated insight description
confidence	float	Model confidence score (0.0-1.0)
urgency	string	Signal priority: low, medium, or high
generatedAt	long	Epoch seconds when this insight was generated
docRefs	array	Source document references (may be null)
metadata	string	JSON string with additional signal metadata (may be null)

Example Response (PRO):

[
  {
    "insightType": "insider_buy_signal",
    "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,
    "metadata": "{\"source\":\"insider_trading\",\"subtype\":\"cluster_buy\",\"insiderCount\":5,\"tradeCount\":12}"
  },
  {
    "insightType": "institutional_position_change",
    "insightText": "12 institutions increased positions in AAPL last quarter, adding 8.3M shares net",
    "confidence": 0.85,
    "urgency": "medium",
    "generatedAt": 1742497200,
    "docRefs": null,
    "metadata": "{\"source\":\"institutional_flows\",\"subtype\":\"inflow\",\"institutionCount\":12}"
  }
]

Preview Response (Free/Unauthenticated):

{
  "isPreview": true,
  "previewReason": "PRO_REQUIRED",
  "insights": [
    {
      "insightType": "insider_buy_signal",
      "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,
      "metadata": null
    }
  ],
  "locked": [
    {
      "insightType": "institutional_position_change",
      "urgency": "medium",
      "generatedAt": 1742497200
    },
    {
      "insightType": "volume_anomaly_high",
      "urgency": "high",
      "generatedAt": 1742490000
    }
  ]
}

The locked array shows that additional signals exist. Users can see the signal type and urgency without the full insight text.

---

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 (PRO):

[
  {
    "insightType": "market_insider_trend",
    "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. Top insider buying: AAPL, NVDA, MSFT, AMZN, GOOGL",
    "confidence": 0.85,
    "urgency": "high",
    "generatedAt": 1742500800,
    "docRefs": null,
    "metadata": "{\"source\":\"market_insights\",\"subtype\":\"insider_trend\",\"buyStockCount\":15,\"sellStockCount\":8}"
  },
  {
    "insightType": "market_institutional_rotation",
    "insightText": "Institutional positioning for 2025-12-31: top inflows in NVDA, AAPL, MSFT, top outflows from META, TSLA",
    "confidence": 0.90,
    "urgency": "medium",
    "generatedAt": 1742497200,
    "docRefs": null,
    "metadata": "{\"source\":\"market_insights\",\"subtype\":\"institutional_rotation\",\"quarter\":\"2025-12-31\"}"
  }
]

Preview Response (Free/Unauthenticated):

{
  "isPreview": true,
  "previewReason": "PRO_REQUIRED",
  "insights": [
    {
      "insightType": "market_insider_trend",
      "insightText": "Insider buying activity across 15 stocks in the past 14 days...",
      "confidence": 0.85,
      "urgency": "high",
      "generatedAt": 1742500800,
      "docRefs": null,
      "metadata": null
    }
  ],
  "locked": [
    {
      "insightType": "market_institutional_rotation",
      "urgency": "medium",
      "generatedAt": 1742497200
    }
  ]
}

---

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)