Sentisense

Read-only financial market data API. Stock prices, sentiment, insider trading, institutional flows, politician trades, AI insights. No trading, no purchases, no write operations, no wallet access.

SentiSense API - Skill File for AI Agents

SentiSense is a read-only financial intelligence API: stock prices, insider/politician trading, institutional flows, AI insights, and news sentiment. No trading, no purchases, no write operations. Free tier available.

Base URL: https://app.sentisense.ai Website: https://sentisense.ai ClawHub Skill: clawhub.ai/TheSentiTrader/sentisense API Docs: https://sentisense.ai/docs/api/ Authentication: API key via X-SentiSense-API-Key header. Get a free key at https://app.sentisense.ai/get-api-key SDKs (optional): Python | Node.js -- source on GitHub. As an AI agent, you're encouraged to call the REST API directly with curl/fetch rather than installing packages.

---

Use & Disclaimer

This skill is an educational data interface to SentiSense's read-only Data API. Output is informational only. It is not investment advice, not a personalized recommendation, and not a solicitation to buy or sell any security. The user is responsible for their own decisions. Use of the API and this skill is subject to the API Terms of Service and Terms of Service.

---

Authentication

bash

# Include API key in header
curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/..."

python

import os
from sentisense import SentiSenseClient
client = SentiSenseClient(api_key=os.environ["SENTISENSE_API_KEY"])

All API endpoints require an API key. Get one free at https://app.sentisense.ai/get-api-key (manage it anytime in the Developer Console).

Access Tiers

Badge	Meaning
Public	Available on all tiers (Free and PRO)
Public (preview)	Free gets limited preview; PRO gets full data
Quota-gated	Consumes monthly quota (Free: limited, PRO: unlimited)
Discovery (no quota cost)	API key required (identity/abuse tracking), but the call does not burn your monthly quota. Rate-limit-per-minute still applies. Used for lightweight metadata endpoints like /stocks/with-kpis and /stocks/{ticker}/kpis/types.
PRO only	Requires PRO subscription

Rate Limits

Tier	Requests/Month	Rate
Free	1,000	30 requests/minute
PRO ($15/mo)	Unlimited	300 requests/minute

Ticker Symbols

Endpoints that take a {ticker} path parameter accept the canonical primary ticker for each company. For dual-class share companies, the API also accepts the secondary class as an alias and resolves it server-side, so you can pass whichever ticker your data source provides.

You pass	Resolves to	Reason
GOOG	GOOGL	Alphabet Class C resolves to Class A
BRK.A, BRK-A, BRKA	BRK.B	Berkshire Class A resolves to Class B
BRK-B, BRKB	BRK.B	Punctuation variants normalized

Aliasing applies to research endpoints (analyst, KPIs, insights, insider, institutional holders, politicians filings, options). Quote and chart endpoints leave the ticker as-is, since market-data providers handle their own symbology. Tickers are case-insensitive. News Corp (NWSA/NWS) and Fox (FOXA/FOX) are NOT aliased to each other (each class is tracked separately).

---

What You Can Build

Smart Money Tracker

Cross-reference insider trading, institutional flows, and politician trades to follow where the smart money is moving. High-conviction signals come from convergence across all three.

• GET /api/v1/insider/activity for market-wide insider buying/selling
• GET /api/v1/institutional/flows for quarterly institutional positioning (optional reportDate; omit for the latest quarter)
• GET /api/v1/politicians/activity for congressional STOCK Act trades
• GET /api/v1/insights/stock/{ticker} for AI signals that combine these data sources

Sentiment-Driven Watchlist

Alert when sentiment shifts for your stocks. Track news volume, social mentions, and baseline deviations.

• GET /api/v2/metrics/entity/{ticker}/metric/sentiment for sentiment time series
• GET /api/v2/metrics/entity/{ticker}/baselines/sentiment for anomaly detection (3-sigma deviations)
• GET /api/v1/documents/ticker/{ticker} for the underlying news and social posts driving the shift

Congressional Trade Monitor

Track what Congress is buying before it moves. Filter by party, chamber, or individual politician. Check if corporate insiders agree.

• GET /api/v1/politicians/activity for recent congressional trades across all members
• GET /api/v1/politicians/member/{slug} for individual politician profiles and trade history
• GET /api/v1/insider/trades/{ticker} to cross-reference with corporate insider activity on the same stock

AI Research Assistant

Generate stock research reports by combining multiple data signals into a single analysis.

• GET /api/v1/stocks/{ticker}/ai-summary?depth=deep for the full AI analysis report
• GET /api/v1/insights/stock/{ticker} for AI-generated stock signals
• GET /api/v1/stocks/fundamentals?ticker={ticker} for a single period of financial statement data
• GET /api/v1/stocks/fundamentals/history?ticker={ticker}&timeframe=annual&limit=10 for multi-year revenue, margin, and free-cash-flow trend to support valuation work
• GET /api/v1/documents/ticker/{ticker} for recent news context

Earnings Calendar Monitor

Position ahead of earnings instead of reacting to them. Pull the forward calendar, intersect it with a watchlist, and pre-load sentiment and smart-money context for the companies reporting soon.

• GET /api/v1/calendar/earnings?week=next for who reports next week (or ?from=&to= for a custom window)
• GET /api/v1/calendar/earnings?ticker={ticker} for a single name's next report date and consensus EPS
• GET /api/v2/metrics/entity/{ticker}/metric/sentiment to gauge positioning into the print
• GET /api/v1/insider/trades/{ticker} to see if insiders moved ahead of the date

Market Dashboard

Real-time market overview combining prices, sentiment, and top signals.

• GET /api/v1/stocks/market-status to check if the market is open
• GET /api/v1/market-summary for AI-generated market headline and analysis
• GET /api/v1/insights/market for the top market-moving signals right now
• GET /api/v1/stocks/prices?tickers=SPY,QQQ,IWM,DIA for index tracking

---

Agent Tips

Workflow Pattern

1. Call GET /api/v1/stocks/market-status first to check if the market is open
2. Call GET /api/v1/institutional/quarters before the institutional endpoints that need a reportDate to get valid values (/flows does not need one; omit it for the latest quarter)
3. All PRO-gated endpoints return {isPreview, previewReason, data}. Always access response["data"] (or response.data). On a preview (FREE) list response a totalCount field is also present: the number of items in the full PRO dataset, so you can show "showing N of totalCount"
4. Use lookbackDays (1-365) on insider and politician endpoints to control the time window

Common Mistakes

• Do NOT hardcode reportDate for institutional endpoints. When you pass one, fetch it from /quarters first; quarters change as new SEC filings come in. (/flows does not require one: omit it for the latest quarter, or pass one for a specific quarter.)
• Do NOT iterate the response directly. Unwrap response["data"] first. All PRO-gated endpoints use the {isPreview, previewReason, data} wrapper
• Do NOT use /api/v1/entity-metrics/* for metrics. These are RETIRED (return 410 Gone). Use /api/v2/metrics/ instead
• The source parameter is case-insensitive. news, NEWS, News all work

Endpoints That Do NOT Exist

Do not hallucinate these. They are not part of the SentiSense API:

• /api/v1/options/flow or /api/v1/dark-pool: these exact paths do not exist. For end-of-day options analytics (IV rank, put/call percentile, 25-delta skew, open-interest walls, max pain, unusual-by-volume contracts) use the Options Intelligence endpoints instead: /api/v1/options/overview and /api/v1/stocks/{ticker}/options/summary. We do not attribute tick-level order flow (no buy/sell aggressor tagging) and we have no dark-pool data
• /api/v1/earnings: for the earnings calendar use /api/v1/calendar/earnings; for reported financials use /api/v1/stocks/fundamentals (single period) or /api/v1/stocks/fundamentals/history (multi-period trend, up to 40 quarters or 20 years)
• /api/v1/alerts or /api/v1/notifications: alerts are user-facing only, not available via API
• /api/v1/chat or /api/v1/ask: the AI chat is not accessible via API
• /api/v2/sentiment: the correct path is /api/v2/metrics/entity/{id}/metric/sentiment
• /api/v1/congress or /api/v1/congressional: the correct path is /api/v1/politicians

---

Stocks API (/api/v1/stocks)

GET /api/v1/stocks/price

Real-time stock price. Public.

Param	Type	Required	Description
ticker	string	Yes	Stock ticker (e.g., AAPL)

bash

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/price?ticker=AAPL"

Response: { ticker, currentPrice, change, changePercent, previousClose, volume, timestamp, expiresEpochSecond, extendedHours? }.

currentPrice is always the regular-session price: live last trade during RTH (09:30 to 16:00 ET), most recent regular-session close otherwise. The optional extendedHours field is present only during pre-market (04:00 to 09:30 ET) or after-hours (16:00 to 20:00 ET) and carries { session: "pre" | "post", price, change, changePercent }, where change / changePercent are computed vs currentPrice.

GET /api/v1/stocks/prices

Batch real-time prices. Public. Returns a JSON array; each element has the same shape as /price (including a ticker field and an optional extendedHours object).

Param	Type	Required	Description
tickers	string	Yes	Comma-separated (e.g., AAPL,TSLA,NVDA)

GET /api/v1/stocks/chart

Historical OHLCV chart data. Public.

Param	Type	Required	Description
ticker	string	Yes	Stock ticker
timeframe	string	No	1D, 5D, 1W, 1M, 3M, 6M, 1Y, ALL (default: 1M)
range	string	No	Alias: 5d, 1mo, 3mo, 6mo, 1y (alternative to timeframe)

Each bar includes timestamp (Unix ms), date, open, high, low, close, volume, and session. The session field is pre (04:00 to 09:30 ET), regular (09:30 to 16:00 ET), or post (16:00 to 20:00 ET) for intraday timeframes (1D, 5D, 1W, 1M); it is null for daily and weekly bars (3M and longer) that span whole sessions. The 1M timeframe is filtered to regular-session bars only.

GET /api/v1/stocks

List all tracked ticker symbols. Public.

GET /api/v1/stocks/detailed

All stocks with company name, KB entity ID, URL slug, and precomputed socialDominance ({ value, rank, percentile }, daily refresh, null when no signal). Public.

Example: sort the universe by share of voice without any second request, or filter by socialDominance.rank <= 50 for the top-50 most discussed names.

GET /api/v1/stocks/popular

Popular stock tickers. Public.

GET /api/v1/stocks/popular/detailed

Popular stocks with company details (same schema as /detailed). Public.

GET /api/v1/stocks/images

Company logo URLs. Public.

Param	Type	Required	Description
tickers	string	Yes	Comma-separated tickers (max 600)

GET /api/v1/stocks/descriptions

Company profiles with branding, industry, and market cap; sector when available (often absent). Public.

Param	Type	Required	Description
tickers	string	Yes	Comma-separated tickers

GET /api/v1/stocks/{ticker}/profile

Company profile (CEO, sector, industry). Public.

GET /api/v1/stocks/{ticker}/similar

Peer/similar stocks. Public.

Param	Type	Required	Default	Description
limit	int	No	5	Max results

GET /api/v1/stocks/{ticker}/entities

Related knowledge base entities (CEO, products, partners). Public. Each entry carries a urlSlug (e.g. Tim-Cook) that plugs into the Metrics API {entityId} parameter.

GET /api/v1/stocks/{ticker}/ai-summary

AI-generated stock analysis report. PRO (Free: depth=basic unlimited, depth=deep limited to 10/month). depth=basic returns a preheader summary. depth=deep returns a full multi-section report. Exhausting the depth=deep monthly view allowance returns 429 with {error: "quota_exceeded", ...}, the same contract as every other quota-gated endpoint.

Param	Type	Required	Default	Description
depth	string	No	basic	basic or deep
forceRefresh	boolean	No	false	Generate fresh report

Response: flat object (no {isPreview, data} wrapper).

Field	Type	Notes
ticker	string
companyName	string
status	string	READY, NOT_AVAILABLE, or ERROR
statusReason	string or null	Present on NOT_AVAILABLE / ERROR only
reportType	string	SUMMARY for depth=basic, FULL for depth=deep
version	integer	Report date encoded as yymmdd (e.g. 260520)
lastUpdated	long	Epoch milliseconds
sections	object	Section name to {content, directives}. Present on depth=deep only.
sectionOrder	string[]	Ordered section keys for rendering. Present on depth=deep only.
moatRating	integer or null	Proprietary moat quality score 0-10 (network effects, switching costs, intangibles, cost advantages, efficient scale). Null if not yet assessed for this ticker.
aiDisruptionRisk	string or null	Low, Medium, High, or Critical. Measures AI revenue-displacement exposure. Null if not yet assessed.

GET /api/v1/stocks/{ticker}/metrics/{metricType}/breakdown

Sentiment or mention metrics breakdown by sub-entities. Public.

Param	Type	Required	Description
metricType	path	Yes	sentiment or mentions
startTime	long	Yes	Start time in epoch ms
endTime	long	Yes	End time in epoch ms

GET /api/v1/stocks/market-status

Current market open/closed status. API key required.

Response: { status: "open" | "closed", timestamp: <epoch_ms> }. The timestamp is a numeric epoch milliseconds value (not a string).

GET /api/v1/stocks/fundamentals

Financial statement data. Public.

Param	Type	Required	Default	Description
ticker	string	Yes	-	Stock ticker
timeframe	string	No	quarterly	quarterly or annual
fiscalPeriod	string	No	-	e.g., Q4
fiscalYear	int	No	-	e.g., 2024

GET /api/v1/stocks/fundamentals/current

Most recent fundamental data snapshot. Public.

Param	Type	Required	Description
ticker	string	Yes	Stock ticker

GET /api/v1/stocks/fundamentals/history

Multi-period history of full financial statements (income statement, balance sheet, cash flow), one entry per fiscal quarter or year, newest first. Use for margin trends, multi-year comparisons, or as the input to a valuation model. Not the same endpoint as /fundamentals (single period) or /fundamentals/historical/revenue (income-statement lines only, no balance sheet or cash flow). Public.

Param	Type	Required	Default	Description
ticker	string	Yes	-	Stock ticker
timeframe	string	No	quarterly	quarterly or annual
limit	int	No	12 quarterly / 10 annual	Periods to return, capped at 40 quarterly / 20 annual

Response includes count (periods actually returned, can be less than limit), reason (non-null only when periods is empty, e.g. a recent listing), and dataSource (deprecated: always an empty string, kept for response-shape compatibility, slated for removal).

GET /api/v1/stocks/fundamentals/periods

Available fiscal periods. Public.

Param	Type	Required	Description
ticker	string	Yes	Stock ticker

GET /api/v1/stocks/fundamentals/historical/revenue

Historical income-statement lines per period: revenue, gross profit, operating income, net income, and EPS. Response wraps them in dataPoints (not periods like /fundamentals/history), plus count, dataSource, and reason. For full statements including balance sheet and cash flow, use /fundamentals/history instead. Public.

Param	Type	Required	Default	Description
ticker	string	Yes	-	Stock ticker
timeframe	string	No	quarterly	quarterly or annual

GET /api/v1/stocks/short-interest

Short interest data from FINRA. Public.

Param	Type	Required	Default	Description
ticker	string	Yes	-	Stock ticker
limit	int	No	24	Max data points

GET /api/v1/stocks/float

Float information (shares outstanding, public float). Public.

Param	Type	Required	Description
ticker	string	Yes	Stock ticker

GET /api/v1/stocks/short-volume

Short volume trading data. Public.

Param	Type	Required	Default	Description
ticker	string	Yes	-	Stock ticker
limit	int	No	90	Max data points

GET /api/v1/stocks/{ticker}/quote

Aggregate quote snapshot: live price, today OHLC, 52-week range, market cap, P/E, EPS TTM, dividend yield, 200-day moving average. Single call for detail pages. API key required.

Response: { ticker, currentPrice, change, changePercent, volume, open, dayHigh, dayLow, previousClose, week52High, week52Low, marketCap, peRatio, epsTTM, dividendYield, movingAverage200Day, timestamp, extendedHours? } -- all fields except ticker are nullable. currentPrice is always the regular-session price; the optional extendedHours object ({ session, price, change, changePercent }) is present only during pre-market or after-hours. movingAverage200Day is null when fewer than 200 trading days of history exist. Cached 15 s server-side.

ETF tickers (e.g. VTI, SPY) return 400 ticker_is_etf from this endpoint. Use GET /api/v1/etfs/{ticker}/quote instead, which returns AUM, expense ratio, NAV, and inception date rather than market cap, P/E, and EPS.

GET /api/v1/stocks/{ticker}/kpis

Company-specific KPI time-series. Curated GAAP and non-GAAP metrics from earnings filings: iPhone unit sales, Tesla deliveries, AWS revenue, Netflix paid net adds, etc. PRO (preview) -- Free: metadata only with empty kpis list, PRO: full series. Returns 404 for tickers without curated coverage.

Coverage today: near-complete for the S&P 500 plus extended universe (~500 tickers). Use GET /api/v1/stocks/with-kpis to enumerate.

Response wrapper: { isPreview, previewReason, data: CompanyKpis }.

CompanyKpis shape: { ticker, companyName, cik, lastUpdated, kpis: KpiSeries[] }.

KpiSeries shape: { id, name, category, unit, displayFormat, chartType, values: KpiDataPoint[], sourceRef, discontinued, discontinuedNote }. id is a stable per-ticker identifier (e.g. iphone_revenue). category is one of product_revenue, segment_revenue, unit_economics, etc. chartType is bar or line.

KpiDataPoint shape: { period, date, value, isEstimate }. period is the fiscal label (e.g. Q2 FY2026); date is the ISO close date.

GET /api/v1/stocks/with-kpis

List every ticker with curated KPI coverage. Sorted alphabetically. Builder discovery: render a supported-tickers page or seed a watchlist without 404-probing one ticker at a time. Discovery (no quota cost) -- API key required for identity/abuse tracking, but the call does not consume your monthly quota. Rate-limit-per-minute still applies.

Response: { count, tickers: KpiCoverageEntry[] } where each entry is { ticker, companyName, lastUpdated, kpiCount }.

python

client = SentiSenseClient(api_key=os.environ["SENTISENSE_API_KEY"])
coverage = client.list_kpi_coverage()
print(f"{coverage.count} tickers covered")
for entry in coverage.tickers[:5]:
    print(f"  {entry.ticker}: {entry.kpiCount} KPIs (refreshed {entry.lastUpdated})")

GET /api/v1/stocks/{ticker}/kpis/types

Lightweight KPI metadata tuples for a ticker, without the full series payload. Mirrors /api/v1/insights/stock/{ticker}/types. Useful for letting an agent or UI decide what to fetch before committing to the heavy data call. Discovery (no quota cost) -- API key required, no quota burn.

Response: bare array of { id, name, category, chartType }. Returns 404 if the ticker has no curated KPIs.

python

types = client.get_kpi_types("AAPL")
for t in types:
    print(f"  {t.id} ({t.chartType}): {t.name}")

---

Entities API (/api/v1/kb)

GET /api/v1/kb/entities/search

Search the knowledge base for the people, companies, products, and organizations SentiSense tracks, and get the handle to query their metrics. Public (API key required).

Param	Type	Required	Default	Description
q	string	Yes	-	Name, alias, ticker, or slug fragment (case-insensitive, minimum 2 characters)
type	string	No	all	company, country, etf, organization, person, product, topic
limit	int	No	10	Max results (capped at 25)

Response: array of {name, urlSlug, type, ticker} matches, best first. ticker is null for entities without one. Feed the urlSlug (or ticker) into the Metrics API {entityId} parameter:

text

GET /api/v1/kb/entities/search?q=pelosi -> [{"name": "Nancy Pelosi", "urlSlug": "Nancy-Pelosi", "type": "person", "ticker": null}]
GET /api/v2/metrics/entity/Nancy-Pelosi/metric/sentiment

People, products, and organizations have the same metrics surface as stocks, so this unlocks queries like a politician's mention volume, a CEO's SentiSense Score (.../entity/Jensen-Huang/metric/sentisense), or crowd sentiment on a product versus its parent ticker.

GET /api/v1/kb/entities/popular

Curated list of high-profile tracked entities (major CEOs, political figures, the Federal Reserve). Public (API key required). Returns {displayName, type, urlSlug, relatedStock} entries; use as an autocomplete seed list without issuing a search.

Metrics API (/api/v2/metrics)

Time series metrics for stocks and entities: mentions, sentiment, social dominance, and more. The {entityId} path segment accepts a stock ticker (e.g. AAPL) or an entity urlSlug (e.g. Nancy-Pelosi); both are case-insensitive, and a ticker-shaped identifier always means the listed company. Discover handles with GET /api/v1/kb/entities/search?q= or GET /api/v1/stocks/{ticker}/entities. An unknown identifier returns 404 entity_not_found with up to three suggestions.

Every metric type (mentions, sentiment, sentisense, social_dominance) is available on the Free tier: no PRO subscription needed. All metrics endpoints are Quota-gated: an API key is required and each request counts against your monthly quota (Free: 1,000 requests/month; PRO: no monthly cap). Per-minute rate limits apply on every tier.

GET /api/v2/metrics/entity/{entityId}/metric/{metricType}

Time series metric data for a stock or entity. Quota-gated -- all metric types (mentions, sentiment, sentisense, social_dominance) are available on the Free tier.

Param	Type	Required	Default	Description
entityId	path	Yes	-	Stock ticker (e.g., AAPL) or entity urlSlug (e.g., Nancy-Pelosi)
metricType	path	Yes	-	mentions, sentiment, sentisense, social_dominance
startTime	long	No	7 days ago	Epoch milliseconds
endTime	long	No	now	Epoch milliseconds
maxDataPoints	int	No	-	Downsample to N data points

Response: an array of points ordered ascending by timestamp. Each point exposes a flat value scalar alongside the full metricValue object:

json

[
  {
    "timestamp": 1780372800000,
    "metricType": "SENTIMENT",
    "value": 0.42,
    "metricValue": { "type": "ValueMetricValue", "valueType": "MEAN", "value": { "value": 0.42 } }
  }
]

Read the scalar from the flat value (the polarity for sentiment, the count for mentions). It saves you walking the nested metricValue.value (count metrics) or metricValue.value.value (value metrics), whose depth varies by metric type. A point with no reading omits value. To derive the current reading and its change: points are time-ascending, so the current value is the last point's value, and the change is the last point's value minus the prior point's (or minus the first point's for the whole window). A window with 0 or 1 point has no derivable trend, so widen startTime rather than reporting a change.

GET /api/v2/metrics/entity/{entityId}/distribution/{metricType}

Distribution of a metric across a dimension (e.g., mentions by source). Quota-gated, available on the Free tier.

Param	Type	Required	Default	Description
entityId	path	Yes	-	Stock ticker or entity urlSlug
metricType	path	Yes	-	Metric type key
dimension	string	Yes	-	Dimension to slice by (e.g., source)
startTime	long	No	7 days ago	Epoch milliseconds
endTime	long	No	now	Epoch milliseconds

GET /api/v2/metrics/entity/{entityId}/metric/{metricType}/mean-by/{dimension}

Mean of a metric per dimension value over a time window (e.g., per-source mean sentiment). Quota-gated, available on the Free tier.

Param	Type	Required	Default	Description
entityId	path	Yes	-	Stock ticker or entity urlSlug
metricType	path	Yes	-	Metric type key (e.g., sentiment)
dimension	path	Yes	-	Dimension to group by (e.g., source)
startTime	long	No	7 days ago	Epoch milliseconds
endTime	long	No	now	Epoch milliseconds

Response: flat map of dimension value to mean, e.g. { "NEWS": 0.42, "REDDIT": -0.05 }. For sentiment by source, each value is the average of that source's daily mean readings inside the window; a window with no data returns {}. Returns 400 for an unknown metric type or when startTime is after endTime.

GET /api/v2/metrics/entity/{entityId}/metric/{metricType}/slices

Available slice dimensions for a metric. Quota-gated, available on the Free tier.

GET /api/v2/metrics/entity/{entityId}/baselines/{metricType}

Historical and peer baselines for a metric. Quota-gated, available on the Free tier.

---

Market Mood API (/api/v2/market-mood)

SentiSense's proprietary composite market sentiment index. Combines social sentiment, market direction, risk appetite, social momentum, and S&P 500 trend signals into a single 0-100 score with sector breakdown. Free (API key required). Free for all tiers, but anonymous calls return 401 api_key_required.

GET /api/v2/market-mood

Composite market sentiment score with history and sector breakdown.

Param	Type	Required	Default	Description
days	int	No	180	Days of history to return

Response shape:

json

{
  "market": {
    "currentScore": 62.88,
    "phase": "Optimism",
    "weeklyChange": -2.3,
    "signals": [
      {"key": "social_sentiment", "label": "Social Sentiment", "value": 54.95, "change": -1.2},
      {"key": "market_direction", "label": "Market Direction", "value": 71.0, "change": 3.1},
      {"key": "fear_gauge", "label": "Risk Appetite", "value": 58.4, "change": null},
      {"key": "social_momentum", "label": "Social Momentum", "value": 62.1, "change": -0.5},
      {"key": "spy_trend", "label": "S&P 500 Trend", "value": 68.9, "change": 2.0}
    ],
    "history": [
      {"date": "2026-04-01", "timestamp": 1743465600000, "score": 65.2,
       "socialSentiment": 56.1, "marketDirection": 72.0, "fearGauge": 61.0,
       "socialMomentum": 63.5, "spyTrend": 70.0}
    ]
  },
  "sectors": {
    "Technology": {"currentScore": 71.2, "phase": "Greed", "weeklyChange": 1.5},
    "Healthcare": {"currentScore": 48.3, "phase": "Neutral", "weeklyChange": -3.1}
  }
}

Phase interpretation (market.phase and each sector's phase, by score): 0-15 Extreme Fear, 16-30 Fear, 31-45 Anxiety, 46-55 Neutral, 56-70 Optimism, 71-85 Greed, 86-100 Extreme Greed. phase is "---" when the score is null.

Node SDK:

javascript

const mood = await client.marketMood.get();
console.log(mood.market.currentScore, mood.market.phase);

---

Documents & News API (/api/v1/documents)

Note: Document responses include a url field but no headline or title text. The API provides derived analytics (sentiment, entities, reliability), not source content. The sourceName field identifies the publisher. If your application needs to display titles, the url field links to the original source. Any content retrieval from source URLs is your application's independent action, subject to the source platform's terms. See our API Terms of Service.

GET /api/v1/documents/ticker/{ticker}

News and social posts for a stock with sentiment scores. Public.

Param	Type	Required	Default	Description
source	string	No	all	NEWS, REDDIT, X, SUBSTACK, YOUTUBE
days	int	No	7	Lookback in days (1-365)
hours	int	No	-	Lookback in hours, 1-8760 (overrides days). Out-of-range values return 400
limit	int	No	200	Max results (capped at 200)

Response: { documents: [...], totalCount, searchTicker, source, startDate, endDate }. Each document includes: id, url, source, sourceName, published, averageSentiment, reliability, sentiment[]. Per-entity sentiment classifies each mentioned entity as POSITIVE/NEGATIVE/NEUTRAL.

GET /api/v1/documents/ticker/{ticker}/range

Documents within a date range. Public.

Param	Type	Required	Description
startDate	ISO date	Yes	e.g., 2025-01-01
endDate	ISO date	Yes	e.g., 2025-01-31
source	string	No	Filter by source
limit	int	No	Max results (capped at 200)

GET /api/v1/documents/entity/{entityId}

Documents mentioning a knowledge base entity. Public. Use URL-safe format: kb-person-67 instead of kb/person/67.

GET /api/v1/documents/search

Smart search with natural language queries. Public.

Param	Type	Required	Default	Description
query	string	Yes	-	e.g., AAPL earnings, Elon Musk TSLA
source	string	No	all	Filter by source
days	int	No	7	Lookback in days
limit	int	No	200	Max results (capped at 500)

GET /api/v1/documents/source/{source}

Latest documents from a specific source. Public.

Param	Type	Required	Description
source	path	Yes	NEWS, REDDIT, X, SUBSTACK, YOUTUBE
days	int	No	Lookback in days
limit	int	No	Max results (capped at 500)
sort	string	No	latest (default, newest first) or top (reliability-first: recent documents are grouped into freshness buckets and ranked by publisher reliability within each bucket, so high-authority publishers surface first). Any other value returns 400.

GET /api/v1/documents/stories

AI-curated news story clusters. Public.

Param	Type	Required	Default	Description
limit	int	No	20	Max stories (capped at 50)
days	int	No	7	Lookback in days (max 15)
offset	int	No	0	Pagination offset

Response: Story objects with a top-level id AND clusterId (both equal to the cluster id -- pass either to /documents/stories/{clusterId}), plus cluster.title, cluster.averageSentiment, tickers, displayTickers, impactScore (0-10), brokeAt (epoch seconds, nullable), cluster.clusteredAt (epoch seconds). Use tickers (bare symbols, e.g. ["AAPL"]) programmatically; displayTickers are human-formatted labels (e.g. ["Apple Inc (AAPL)"]) for display only, do not parse symbols out of them. The cluster.createdAt field (epoch millis) is deprecated and will be removed on or after 2026-08-16; use cluster.clusteredAt.

GET /api/v1/documents/stories/ticker/{ticker}

News stories for a specific stock. Public. Takes limit only (default 5, capped at 20): there is no lookback window here, so days / hours / filterHours are ignored. Use /documents/stories with filterHours for a freshness window.

GET /api/v1/documents/stories/{clusterId}

Full detail for a single story cluster. Public -- Free: 10 story views/month, PRO: unlimited. Each list item from /stories and /stories/ticker/{ticker} carries a top-level id AND a clusterId (both equal to the cluster id); pass either one here as {clusterId}.

Param	Type	Required	Description
clusterId	path	Yes	Story cluster ID (from /stories or /stories/ticker/{ticker})

Response: a flat story object (no {isPreview, data} wrapper) containing SentiSense-generated content and derived data only: id, createdAt, lastUpdatedAt; AI-written content (title, summarizedContent, narrativeBody, bullishView, bearishView, aspectPerspectives); citationLinks (map of docN markdown references in narrativeBody to public article URLs); computed metrics (averageSentiment, momentumScore, aiConfidence); source metadata (clusterSize, sourcesList, primaryCategory, dominantEventType, publishersList, primaryPublisher, topPublishers); tickers, displayTickers, primaryEntityNames, relatedEntities; archived, totalDocuments.

Consistent with the documents policy above, publisher headlines, article text, and images are never included: the title and narrative are AI-generated by SentiSense, and citationLinks point to the original sources.

---

Institutional Flows API (/api/v1/institutional)

Data from SEC 13F-HR filings. Filer categories: INDEX_FUND, HEDGE_FUND, ACTIVIST, PENSION, BANK, INSURANCE, MUTUAL_FUND, SOVEREIGN_WEALTH, ENDOWMENT, CONGLOMERATE, OTHER.

Important: /flows no longer requires reportDate: omit it to get the latest available quarter (the response is labeled with isPending + filer coverage), or pass one explicitly for a specific quarter. The other institutional endpoints (except /quarters) still require a reportDate. When you need one, call GET /quarters first to get valid dates; do not hardcode them. For a fully-filed quarter, use the reportDate from the first quarter with pending:false (the most-recent quarter is pending:true while inside the 45-day 13F filing window and holds only early filers; see /quarters below).

GET /api/v1/institutional/quarters

Available 13F reporting quarters. Public. Call this first.

Response: array of { value, label, reportDate, pending } objects sorted newest-first. pending is a boolean. Use the reportDate of the first quarter with pending:false; the most-recent quarter is pending:true while inside the 45-day 13F filing window and holds only early filers. Pass that reportDate (e.g., "2025-12-31") when calling other institutional endpoints.

GET /api/v1/institutional/flows

Aggregate institutional buying/selling per ticker. Public (preview) -- Free: top 5, PRO: full data.

Param	Type	Required	Description
reportDate	ISO date	No	Quarter to fetch (e.g., 2025-12-31). Omit to get the latest available quarter, including a still-open one; the response labels it with isPending + filer coverage. Pass a reportDate from /quarters for a specific quarter.
limit	int	No	Max results per direction (default: 50, max: 100)

Response: { isPreview, previewReason, data: { inflows: [...], outflows: [...], reportDate, isPending, filerCount, baselineFilerCount } }. reportDate is the quarter served (useful when you omitted the param). isPending is true when that quarter is still inside the 45-day 13F filing window, so only early filers are represented; when pending, filerCount and baselineFilerCount give the coverage (e.g., 578 of 8789 filers) and are null otherwise. Each flow includes net share changes, new/closed positions, and per-category breakdowns (indexFundNetChange, hedgeFundNetChange, etc.). Flows are ranked by dollarFlowUsd (= netSharesChange × avgClosePrice): inflows DESC, outflows ASC. avgClosePrice is null and dollarFlowUsd is 0 for tickers without a cached quarterly price; clients should fall back to netSharesChange for those rows.

GET /api/v1/institutional/holders/{ticker}

Institutional holders for a stock. Public (preview) -- Free: top 5, PRO: full data.

Param	Type	Required	Description
reportDate	ISO date	Yes	Quarter end date
limit	int	No	Page size (1-1000). When present, returns a sorted page plus returnedCount/offset and a notableChanges summary; when omitted, returns the full list (legacy). Mega-caps have 5,000+ holders, so paging is recommended.
offset	int	No	Page start within the sorted list (default 0; used with limit)
sortBy	string	No	shares (default), valueUsd, or sharesChangePct (used with limit)
sortDir	string	No	desc (default) or asc (used with limit)

Response: { isPreview, previewReason, data: { ticker, companyName, reportDate, totalInstitutionalShares, holderCount, holders: [...] } }. The holder list is nested at data.holders (not data directly). Each holder includes filer name, category, shares, value, change type (NEW/INCREASED/DECREASED/SOLD_OUT/UNCHANGED). holderCount is always the full-quarter count; on paged requests data also carries returnedCount, offset, and notableChanges ({count, top}: holders with a 10%+ change on 10k+ shares, top 5 by dollar impact).

GET /api/v1/institutional/activist

Activist investor positions (NEW or INCREASED stakes). Public (preview) -- Free: top 3, PRO: full data.

Param	Type	Required	Description
reportDate	ISO date	Yes	Quarter end date

GET /api/v1/institutional/bonds

Convertible bond flows grouped by base ticker. Public (preview) -- Free: top 3, PRO: full data.

Param	Type	Required	Description
reportDate	ISO date	Yes	Quarter end date

GET /api/v1/institutional/options

Institutional options activity with call/put breakdown. Public (preview) -- Free: top 3, PRO: full data.

Param	Type	Required	Description
reportDate	ISO date	Yes	Quarter end date

GET /api/v1/institutional/institutions

Discover the universe of institutions: paginated, AUM-ranked list of filers (slug + metadata) so you can find what to query without knowing slugs upfront. Each institution is rolled up by parent filer, so a multi-filer manager (e.g. Vanguard) appears once with combined AUM. Summary only; use /institution/{slugOrCik} for full holdings. API key required, quota-exempt (per-minute rate limits still apply); full list for every key holder.

Param	Type	Required	Description
category	string	No	Filer category: INDEX_FUND, HEDGE_FUND, ACTIVIST, PENSION, BANK, INSURANCE, MUTUAL_FUND, SOVEREIGN_WEALTH, ENDOWMENT, CONGLOMERATE, OTHER
minAumUsd	long	No	Minimum total AUM in USD (e.g. 10000000000)
limit	int	No	Page size (default: 50, max: 200)
offset	int	No	Pagination offset (default: 0)
sort	string	No	aumDesc (default), aumAsc, or nameAsc. Deterministic ordering, so pagination is stable.
quarter	string	No	AUM snapshot quarter as YYYYQN (e.g. 2026Q1); defaults to latest.

Response: { isPreview, previewReason, data: { quarter, totalCount, offset, limit, institutions: [...] } }. isPreview is always false here. Each institution: cik, urlSlug, displayName, filerCategory, totalValueUsd, holdingsCount, multiCikRollup, childCikCount. Bad inputs (unknown category/sort, negative offset/minAumUsd, quarter with no data) return 400.

GET /api/v1/institutional/institution/{slugOrCik}

Full profile, summary stats, and current-quarter equity holdings for a specific institutional filer. Resolved by URL slug (e.g. Berkshire-Hathaway) or numeric CIK (e.g. 1067983). PRO (preview) -- Free: profile + top 10 holdings, PRO: full holdings array. Returns 404 if the slug or CIK is unknown.

Response: { isPreview, previewReason, data: { filerCik, displayName, urlSlug, filerCategory, totalValueUsd, holdingsCount, latestReportDate, quartersTracked, newPositions, increasedPositions, decreasedPositions, soldOutPositions, multiCikRollup, childCikCount, childCiks, holdings: [...] } }. multiCikRollup/childCikCount/childCiks describe parent/subsidiary rollups (e.g. Vanguard) and are present for all tiers (childCiks is null when not a rollup). Holding objects include ticker, companyName, shares, valueUsd, changeType, sharesChange, sharesChangePct, portfolioWeight.

---

Insider Trading API (/api/v1/insider)

SEC Form 4 insider trading data: track buys, sells, awards, and exercises by company officers, directors, and 10%+ shareholders. Updated daily. Includes cluster buy detection (a historically bullish signal).

Insider relationships: OFFICER, DIRECTOR, TEN_PCT_OWNER, OTHER. Each filer also has independent officer, director, tenPctOwner booleans (a person can be both officer and director).

Transaction types: BUY, SELL, EXERCISE, AWARD, GIFT, OTHER. To count open-market activity, filter transactionType to BUY or SELL; AWARD (grants), GIFT, and EXERCISE are not open-market trades and should be excluded from a buys/sells tally. Note the insider endpoint uses BUY/SELL, NOT the politician endpoint's PURCHASE/SALE vocabulary (a filter written for one returns zero on the other).

GET /api/v1/insider/activity

Market-wide insider buying and selling aggregated by ticker. Public (preview) -- Free: top 5, PRO: full data.

Param	Type	Required	Default	Description
lookbackDays	int	No	90	Days to look back (1-365)

Response (FREE tier): { isPreview: true, previewReason: "PRO_REQUIRED", data: { buys: [...], sells: [...] } }. PRO: { isPreview: false, previewReason: null, data: { buys: [...], sells: [...] } }. Each entry: ticker, companyName, tradeCount, insiderCount, totalShares, totalValue, latestDate, latestInsider, latestTitle.

GET /api/v1/insider/trades/{ticker}

Insider transactions for a specific stock, newest first. Public (preview) -- Free: top 5, PRO: full data.

Param	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker (e.g., AAPL)
lookbackDays	int	No	90	Days to look back (1-365)

Response: { isPreview: bool, previewReason: string|null, data: [...] }. Free: top 5 trades, PRO: full list. Each trade: insiderName, insiderTitle, insiderRelation, officer, director, tenPctOwner, transactionDate, filedDate, transactionCode, transactionType, securityTitle, sharesTransacted, pricePerShare, totalValue, sharesOwnedAfter, directOwnership, rule10b51.

python

client = SentiSenseClient(api_key=os.environ["SENTISENSE_API_KEY"])
trades = client.get_insider_trades("AAPL", lookback_days=90)
for t in trades.data:
    print(f"{t['transactionDate']} {t['insiderName']} {t['transactionType']} {t['sharesTransacted']} shares")

GET /api/v1/insider/cluster-buys

Cluster buy signals: stocks where 3+ distinct insiders purchased recently. Public (preview) -- Free: top 5, PRO: full data.

Param	Type	Required	Default	Description
lookbackDays	int	No	90	Days to look back (1-365)

Response: { isPreview: bool, previewReason: string|null, data: [...] }. Free: top 5 signals, PRO: full list. Each entry: { ticker, companyName, insiderCount, tradeCount, totalShares, totalValue, firstBuyDate, lastBuyDate }.

---

Politicians Trading API (/api/v1/politicians)

Congressional STOCK Act trading disclosures: purchases, sales, and exercises by U.S. Senators and Representatives. Updated daily from official filings.

Chambers: SENATE, HOUSE.

Transaction types: PURCHASE, SALE, EXCHANGE, OTHER.

Amount ranges: STOCK Act disclosures report dollar amounts as ranges (e.g., "$1,001 - $15,000"), not exact values. The API returns the raw range string plus parsed amountMin/amountMax.

GET /api/v1/politicians/activity

Recent congressional trades across all politicians, sorted by disclosure date (most recently disclosed first). "Recent" means recently disclosed, not recently traded: a filing can reveal a transaction made up to 45 days earlier. Public (preview) -- Free: top 5, PRO: full data.

Param	Type	Required	Default	Description
lookbackDays	int	No	90	Trailing window applied to the disclosure date (1-365)

Response: { isPreview, previewReason, data: [...] }. Each trade: politicianName, firstName, lastName, chamber, party, state, bioguideId, imageUrl, ticker, assetDescription, assetType (Stock, ETF, or Stock Option), assetMetadata (object: null, or {kind:"OPTION", optionType, strikePrice, expirationDate} for options), transactionType, transactionDate, disclosureDate, disclosureDelayDays, amountRange, amountMin, amountMax, owner, urlSlug.

python

client = SentiSenseClient(api_key=os.environ["SENTISENSE_API_KEY"])
activity = client.get_politician_activity(lookback_days=90)
for trade in activity.data:
    print(f"{trade['politicianName']} ({trade['party']}-{trade['state']}): {trade['transactionType']} {trade['ticker']}")

GET /api/v1/politicians/filings/{ticker}

Congressional trades for a specific stock, sorted by disclosure date (most recently disclosed first). Public (preview) -- Free: top 3, PRO: full data.

Param	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker (e.g., NVDA)
lookbackDays	int	No	90	Trailing window applied to the disclosure date (1-365)

Response: same preview wrapper and trade object schema as /activity.

GET /api/v1/politicians/members

All tracked politicians with trading summaries, sorted by total trade count. Public (preview) -- Free: top 5, PRO: full list.

No parameters.

Response: { isPreview, previewReason, data: [...] }. Each entry: urlSlug, displayName, firstName, lastName, chamber, party, state, bioguideId, imageUrl, totalTrades, purchaseCount, saleCount, latestTradeDate.

GET /api/v1/politicians/member/{slug}

Detailed profile for a single politician: summary stats, recent trades, and top tickers. Public (preview) -- Free: preview-wrapped, PRO: full detail.

Param	Type	Required	Default	Description
slug	path	Yes	-	Politician URL slug (from /members)

Response: { isPreview, previewReason, data: { profile: {...}, recentTrades: [...], topTickers: [...] } }.

---

Insights API (/api/v1/insights)

AI-generated signals for stocks and the overall market. Each insight identifies a specific pattern: insider cluster buying, institutional position changes, volume anomalies, sentiment baseline deviations, and more. Most lists are sorted by urgency then confidence; the per-stock endpoint (/stock/{ticker}) is ranked by importance (relevance, confidence, and recency) so fresh signals lead.

Insight fields: insightId, insightType, category (SENTIMENT/TRENDING/TECHNICAL/FUNDAMENTAL/PERSONALIZED), insightText, confidence (0.0-1.0), urgency (low/medium/high), generatedAt (epoch seconds), docRefs ([{url, type}]).

Response shape (all tiers): { isPreview, previewReason, data: [...] }. Free: top N insights, PRO: full list.

GET /api/v1/insights/stock/{ticker}

AI insights for a specific stock, ranked by importance (relevance, confidence, and recency); data[0] is the top insight. Public (preview) -- Free: top 3, PRO: full list.

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

python

client = SentiSenseClient(api_key=os.environ["SENTISENSE_API_KEY"])
result = client.get_stock_insights("AAPL", urgency="high")
for i in result.data:
    print(f"[{i['urgency'].upper()}] {i['insightType']}: {i['insightText'][:80]}")

GET /api/v1/insights/stock/{ticker}/range

Per-stock insights within a date range, sorted by urgency then confidence. PRO (preview) -- Free: top 3, PRO: full list. Returns 400 invalid_parameter when startDate is after endDate.

Param	Type	Required	Description
ticker	path	Yes	Stock ticker (e.g. AAPL)
startDate	ISO date	Yes	Inclusive
endDate	ISO date	Yes	Inclusive, on or after startDate
urgency	string	No	Filter by low, medium, or high
insightType	string	No	Filter by insight type

GET /api/v1/insights/market

Market-level AI insights: insider buying trends, institutional rotation, and top high-urgency stock signals. Public (preview) -- Free: top 5, PRO: full list.

No parameters required.

python

result = client.get_market_insights()
for i in result.data:
    print(f"[{i['urgency'].upper()}] {i['insightText'][:100]}")

GET /api/v1/insights/latest

Latest AI insights across all tracked stocks, newest first. PRO (preview) -- Free: top 5, PRO: up to limit.

Param	Type	Required	Default	Description
limit	int	No	50	Max results, clamped to 1-200
urgency	string	No	-	Filter by urgency

GET /api/v1/insights/user

Personalized insights for the authenticated user, biased toward their watchlist and portfolio. Falls back to market-level insights when the user has no watchlist. API key required. Returns 401 without credentials.

Param	Type	Required	Default	Description
limit	int	No	20	Max results, clamped to 1-100
category	string	No	-	Filter by category: SENTIMENT, TRENDING, TECHNICAL, FUNDAMENTAL, or PERSONALIZED

Response wrapper is {isPreview: false, previewReason: null, data: [...] } since the endpoint is auth-required.

GET /api/v1/insights/stock/{ticker}/types

Available insight types for a ticker. Public -- no authentication required.

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

Response: string array, e.g. ["insider_buy_signal", "institutional_position_change", "volume_anomaly_high"].

---

Analyst Ratings API (/api/v1/analyst)

Wall Street analyst coverage: aggregate price target band, buy/hold/sell distribution, recent upgrade/downgrade actions, and forward EPS estimates with earnings surprise history. Free users still get the price target band (targetLow, targetMean, targetHigh, numberOfAnalysts, consensusLabel) in full -- it powers the public projection cone. The buy/hold/sell distribution counts and full action/estimate history are PRO-only.

GET /api/v1/analyst/{ticker}/consensus

Aggregate Wall Street consensus: price target band, number of covering analysts, upside-to-current, recommendation distribution. PRO (preview) -- Free: full price band, no buy/hold/sell counts. PRO: full distribution.

Param	Type	Required	Description
ticker	path	Yes	Stock ticker (e.g. AAPL)

Response: { isPreview, previewReason, data: { ticker, currentPrice, targetLow, targetMean, targetHigh, targetMedian, numberOfAnalysts, upsidePercent, consensusLabel, recommendationMean, strongBuy, buy, hold, sell, strongSell, updatedAt } }. The five *Buy/*Sell/hold count fields are zero in the free preview. Returns 404 when no analyst coverage exists for the ticker.

GET /api/v1/analyst/{ticker}/actions

Recent analyst upgrade/downgrade actions for a ticker, newest first. PRO (preview) -- Free: 3 most recent, PRO: full list.

Param	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker
lookbackDays	int	No	90	Days of history to return

Action object: { ticker, actionDate, firm, actionType (UPGRADE/DOWNGRADE/INITIATE/REITERATE/OTHER), fromGrade, toGrade }.

GET /api/v1/analyst/{ticker}/estimates

Forward EPS estimates and recent earnings surprise history. PRO (preview) -- Free: 1 estimate (current quarter) + 2 most recent surprises, PRO: full history.

Param	Type	Required	Description
ticker	path	Yes	Stock ticker

Response: { isPreview, previewReason, data: { estimates: [...], surprises: [...] } }.

GET /api/v1/analyst/activity

Market-wide recent analyst actions across all covered tickers, newest first. PRO (preview) -- Free: 5 most recent, PRO: full list.

Param	Type	Required	Default	Description
lookbackDays	int	No	30	Days of history to return

Same per-action shape as /api/v1/analyst/{ticker}/actions.

---

ETFs API (/api/v1/etfs)

ETF discovery, composition (holdings), and holdings-weighted aggregate views. Funds aren't rated by analysts directly and don't have insiders of their own, so the aggregate endpoints synthesize fund-level views from each constituent's per-stock data, weighted by allocation. Every aggregate response carries a coverage block so consumers see how much of the fund's AUM the underlying data covered.

Coverage: a growing set of widely-traded funds (SPY, QQQ, IWM, VOO, VTI, major SPDR sectors, etc.). Expect coverage and aggregate freshness to keep improving.

GET /api/v1/etfs

List every ETF SentiSense tracks. Sorted by ticker. Discovery (no quota cost) -- API key required, but the call does not consume your monthly quota. No parameters. This exemption applies to this list endpoint only; the per-ticker ETF endpoints below (holdings, quote, aggregates) count against monthly quota as usual.

Response: Array<{ ticker, name, kbEntityId, urlSlug, issuer, trackedIndex, assetClass }>.

GET /api/v1/etfs/{ticker}/holdings

Full composition of an ETF: per-holding weights, freshness timestamps, partial-coverage signal. Free tier (API key required).

Param	Type	Required	Description
ticker	path	Yes	ETF ticker (e.g. QQQ)

Response: { ticker, issuer, issuerEndpoint, asOfDate (ISO date), fetchedAt (epoch seconds), nextRefreshDue (ISO date), totalHoldings, holdings: [{ ticker, name, weightPct, firstSeen (ISO date) }], partial?, totalKnownHoldings? }. Returns 404 for unknown ETFs or commodity-only funds (e.g. GLD) without equity holdings.

GET /api/v1/etfs/{ticker}/quote

Aggregate ETF detail-page quote: live price, today OHLC, 52-week range, trailing-12-month dividend yield, AUM, expense ratio, NAV, inception date. Peer of /api/v1/stocks/{ticker}/quote for fund tickers. API key required.

Param	Type	Required	Description
ticker	path	Yes	ETF ticker (e.g. VTI)

Response: { ticker, currentPrice, change, changePercent, volume, open, dayHigh, dayLow, previousClose, week52High, week52Low, dividendYield, aum, expenseRatio, nav, inceptionDate (ISO date), timestamp, extendedHours? } -- all fields except ticker are nullable. aum is the ETF analogue of marketCap on the stock quote. expenseRatio and dividendYield are decimals (e.g. 0.0003 for 0.03%). Cached 15 s server-side.

Stock tickers (e.g. AAPL) return 400 ticker_is_not_etf from this endpoint. Use GET /api/v1/stocks/{ticker}/quote instead.

GET /api/v1/etfs/{ticker}/aggregates/analyst

Holdings-weighted analyst consensus for an ETF, derived from per-stock coverage of each constituent. Math: weight × per-stock upside, renormalized to the covered subset. API key required. Returns the full response (including topContributors) to every API caller; tiers differ only in per-tier rate limits and quota.

Param	Type	Required	Description
ticker	path	Yes	ETF ticker

Response: { isPreview, previewReason, data: { ticker, asOfDate (ISO date), computedAt (epoch seconds), coverage: { holdingsCount, holdingsCovered, weightCovered, partial?, totalKnownHoldings? }, weightedConsensus: { upsidePercent, consensusLabel ("BUY"|"HOLD"|"SELL"), distribution: { BUY: 0.62, HOLD: 0.31, SELL: 0.07 }, totalAnalysts }, topContributors: [{ ticker, weightPct, upsidePercent, consensusLabel, contributionPp }] } }. Returns 404 when not an ETF or when covered AUM is too low to publish (typically foreign-listed funds).

GET /api/v1/etfs/{ticker}/aggregates/insider

Holdings-weighted SEC Form 4 insider activity for an ETF over a configurable window. API key required. Returns the full response (including topContributors) to every API caller.

Param	Type	Required	Default	Description
ticker	path	Yes	-	ETF ticker
lookbackDays	int	No	30	Trailing window (typical: 30 or 90)

Response: { isPreview, previewReason, data: { ticker, asOfDate (ISO date), computedAt (epoch seconds), lookbackDays, coverage, weightedNetFlow: { netDollars (signed), buyDollars, sellDollars, buyTradeCount, sellTradeCount, distinctInsiderCount }, topContributors: [{ ticker, weightPct, netDollars, weightedNetDollars, tradeCount }] } }.

GET /api/v1/etfs/{ticker}/aggregates/sentiment

Two SentiSense Score readings side-by-side: constituent-weighted (precomputed daily across the fund's holdings) and direct (mentions of the ETF's own ticker). The two can diverge meaningfully and the gap is itself informative. Covers a growing set of widely-traded funds (SPY, QQQ, VOO, VTI, IWM, major SPDR sector funds, and more). Returns 404 for funds outside the current coverage window. API key required.

Param	Type	Required	Description
ticker	path	Yes	ETF ticker

Response: { isPreview, previewReason, data: { ticker, asOfDate (ISO date), computedAt (epoch seconds), coverage, constituentsWeighted: { sentiSenseScore, scoreLabel ("BULLISH"|"NEUTRAL"|"BEARISH"), asOfTimestamp (epoch seconds) }, direct: { ...same shape... } | null } }. The direct block can be null for low-mention funds. Returns 404 when the constituent-weighted metric hasn't been produced for the ticker yet.

---

Options Intelligence API (/api/v1/options, /api/v1/stocks/{ticker}/options)

End-of-day options analytics for US stocks and ETFs, ranked against each ticker's OWN history. Derived nightly from the prior session's full option chain, then reduced to a lean daily aggregate: put/call volume and open interest, an ATM implied-volatility term structure, 25-delta skew, notional premium traded, open-interest walls with max pain, and the session's unusually-active contracts. The product thesis is percentile-first: every reading is served alongside its percentile within that ticker's trailing window (for example "put/call volume at the 92nd percentile of its 1y range"), never a bare cross-sectional number. Readings describe what the chain looks like today versus its own past; they are not forecasts.

This is end-of-day data, latest session (not real-time): asOf is the prior trading day and the blobs refresh each morning after the session closes. Coverage is two universes, discovered differently. Stocks: a bounded universe of the most actively optioned US names, roughly 950 in the latest build (the exact size is in coverageCount) and expanding; the rows of /options/overview are the authoritative list. ETFs: the US ETFs SentiSense tracks (enumerate them with GET /api/v1/etfs) get the same coverage on the same /stocks/{ticker}/options/... paths, and on the overview they are a SEPARATE board: etfRows, never mixed into rows. coverageCount and the market-pulse aggregates describe the stock board only, so an ETF is never counted there. The two boards are ranked independently and must not be merged: every reading is a percentile of that ticker's own trailing history, so an ETF's interestScore is comparable to other ETFs, not to a single stock. A ticker in neither universe returns 200 with data: null from /summary (unknown tickers behave the same), so treat a null as "not covered", not as an error. Separately, a covered ticker that has not yet accumulated enough sessions (roughly 60) or cleared a liquidity floor returns its raw readings with omitted percentiles and no interestScore while its baseline builds.

Access and free-tier gating: all three endpoints require an API key and each call counts against your monthly request quota. The options data itself is additionally tiered by key. PRO keys always get the full response. FREE keys get a working taster: /options/overview returns the top 25 ranked rows (plus all market-pulse aggregates and a totalCount of the full board); /stocks/{ticker}/options/summary returns the full dossier for the first 10 calls each calendar month (monthly reset; data: null responses never spend the meter), then a headline-only preview (asOf, sentiment, ivRank1y, atmIv, pcVol, pcVolPctl1y, maxPain); /stocks/{ticker}/options/history always serves window=1y. Previewed bodies carry isPreview: true and previewReason: "PRO_REQUIRED"; full bodies carry isPreview: false and previewReason: null. Null-valued fields are omitted from the JSON entirely, so check for field presence rather than comparing against null.

GET /api/v1/options/overview

Market-wide Options Radar: two boards plus market-pulse aggregates. rows is one row per covered stock; etfRows is the same row shape for covered ETFs (omitted entirely when a build has none). Both boards arrive ranked by interestScore descending (unscored building-baseline rows last), so the top of the list is the most interesting names today. FREE keys receive the top 25 rows with totalCount; PRO keys receive every row. API key required. No parameters.

Response: { isPreview, previewReason, data }, where data is { asOf, medianIvRank, marketPcVol, extremeCount, coverageCount, rows: [...], etfRows: [...], etfMedianIvRank, etfMarketPcVol, etfExtremeCount, etfCoverageCount }. data is null before the first nightly build populates it. Each board carries its OWN aggregates and they are never blended: medianIvRank / marketPcVol / extremeCount / coverageCount describe the stock board, and the four etf* aggregates describe the ETF board (all four omitted when a build has no ETF rows). etfCoverageCount is the denominator for etfExtremeCount and stays the full board size even on a truncated FREE response. On a FREE key the envelope's totalCount reports the full stock board and data.etfTotalCount reports the full ETF board. For ETF rows, sector carries the fund's asset class (Equity, Bond, Commodity, ...) rather than a GICS sector. Each row, in either board:

Field	Type	Notes
ticker	string	Primary ticker
name	string	Company name (null if unmapped)
sector	string	Sector (null if unmapped)
asOf	ISO date	Session date of this row's snapshot
sentiment	number	Options-implied sentiment, -1 to +1 (null on cold start)
interestScore	number	Composite 0-100 blend of how extreme the row's readings are (null while the baseline builds)
pcVol	number	Put/call volume ratio today
pcVolPctl1y	number	Percentile (0-100) of pcVol in the trailing 1y window
atmIv	number	ATM implied volatility, as a fraction (0.42 = 42%)
ivRank1y	number	IV rank (0-100) of atmIv in its trailing 1y range
skew25d	number	25-delta skew, iv25p - iv25c, a fraction on the same scale as IV (0.03 = 3 IV points)
skewPctl1y	number	Percentile (0-100) of skew25d in the trailing 1y window
notionalVol	number	Premium traded today (sum of volume × mark × 100)
ivMove20	number	Signed change of atmIv vs its ~20-session mean; rank the "biggest IV moves" pill by its absolute value
observations1y	integer	Trailing-1y observation count (drives the building-baseline state)
unusualCount	integer	Unusually-active contracts this session
maxVolOiRatio	number	Largest volume/open-interest multiple among them
maxUnusualPremium	number	Largest premium ($) among them
wallSide	string	Side of the single heaviest OI wall, call or put
wallStrike	number	Strike of that wall
wallShare	number	That wall's share of its side's open interest (0-1)

Rows arrive ranked by interestScore; re-sort client-side for other views (notionalVol for "most active", maxUnusualPremium for unusual activity). Sort each board on its own; never concatenate rows and etfRows into one ranking.

bash

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/options/overview"

GET /api/v1/stocks/{ticker}/options/summary

The latest options dossier for one stock or ETF: today's aggregate, its percentile context, the open-interest wall structure with max pain, and the session's unusual contracts. API key required.

Param	Type	Required	Description
ticker	path	Yes	Stock or ETF ticker (e.g., NVDA, SPY)

Response: { isPreview, previewReason, data }, where data is null when the ticker is outside the covered universe (unknown tickers behave the same; null responses never spend the FREE dossier meter) or has no snapshot yet, otherwise { asOf, sentiment, latest, context, oiWalls, unusual } (FREE keys: full for the first 10 calls/month, then the headline preview described in the access paragraph):

• latest (today's daily aggregate): { date, callVol, putVol, callOi, putOi, pcVol, pcOi, vwIv, atmIv, skew25d, atmIv60, atmIv90, iv25c, iv25p, netDelta, notionalVol, contracts }. atmIv60/atmIv90 are the ~60d/~90d ATM IV proxies (the term structure); iv25c/iv25p are the raw 25-delta call/put IVs, and skew25d == iv25p - iv25c. Ratio/IV fields are omitted when undefined (e.g. pcVol when call volume is 0).
• context (percentiles of latest): { pcVolPctl1y, pcVolPctl5y, pcOiPctl1y, ivRank1y, skewPctl1y, observations1y }. Any percentile whose trailing window has too few observations is omitted (building baseline).
• oiWalls (point-in-time, for the dossier expiry): { expiry, maxPain, callWalls: [{ strike, oi }], putWalls: [{ strike, oi }] }, up to 3 walls per side, descending by open interest.
• unusual (top 5 by premium): [{ contract, type, strike, expiry, dte, volume, oi, volOiRatio, premium }] -- contracts whose volume far exceeds open interest (fresh positioning). contract is the OCC-style option symbol (e.g. NVDA260821C00200000).

bash

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/NVDA/options/summary"

ETFs use the same path, and it is the only way to reach them since the Radar board is stocks-only:

bash

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/SPY/options/summary"

GET /api/v1/stocks/{ticker}/options/history

The daily-aggregate time series for one stock or ETF, ascending by date. API key required.

Param	Type	Required	Default	Description
ticker	path	Yes	-	Stock or ETF ticker
window	string	No	1y	1y, 2y, or 5y (5y returns all stored history, currently about two years); any other value clamps to 1y. FREE keys always receive 1y

Response: { isPreview, previewReason, data }, where data is { ticker, window, series: [...] } and each element of series has the same shape as the latest aggregate above ({ date, callVol, putVol, ..., contracts }). An empty series means the ticker has no stored aggregates yet.

bash

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/NVDA/options/history?window=1y"

When to use these: call /options/overview (no ticker) for the market-wide read of where options activity and implied volatility are unusual today, then drill into a name with /stocks/{ticker}/options/summary for its full dossier (walls, max pain, unusual contracts). For a macro or sector read, use data.etfRows from the overview, or go straight to an ETF dossier (SPY, QQQ, IWM, TLT, GLD, the sector XL* funds). Use /stocks/{ticker}/options/history to chart how a reading (IV, put/call, skew) has trended over time (history is backfilled from mid-2024, so 5y currently returns about two years). Every value is a percentile of that stock's own past, so read it as "elevated or muted versus this stock's own history", not as a cross-stock ranking.

---

Market Summary API (/api/v1/market-summary)

AI-generated market overview with headline and expanded markdown analysis.

GET /api/v1/market-summary

AI market summary with headline and markdown analysis. Public. No parameters required.

Response:

Field	Type	Description
lastUpdated	long	Epoch milliseconds when data was last updated
headline	string?	1-2 sentence market punchline
expandedContent	string?	Full markdown analysis
generatedAt	long?	Epoch seconds when AI summary was generated

---

Trackers API (/api/v1/trackers)

Observational data products. Every tracker returns the same standardized envelope, so one renderer per viewType covers every current and future SentiSense tracker. Full docs: https://sentisense.ai/docs/api/trackers.

GET /api/v1/trackers

Discovery listing of every publicly-visible tracker.

Response: {"trackers": TrackerListing[]} where each TrackerListing has:

Field	Type	Description
trackerId	string	Slug for the detail endpoint
displayName	string	Hub-card title
category	string	Coarse grouping (institutional, etc.)
description	string	One-sentence subtitle
viewType	string	Renderer hint. Phase 1 publishes table
accessTier	string	free or pro. pro trackers truncate to a free preview for FREE callers; free trackers return the full snapshot to everyone
methodologyAnchor	string	Fragment on /methodology for the tracker
refreshIntervalSeconds	int	Expected refresh cadence
canonicalUrl	string	Detail endpoint path

GET /api/v1/trackers/{trackerId}

Standardized snapshot envelope for one tracker. Returns:

text

{"isPreview": false, "previewReason": null, "data": TrackerSnapshot}

A pro tracker served to a FREE caller truncates rows[] and sets isPreview: true, previewReason: "PRO_REQUIRED" plus totalCount; free trackers and PRO callers get the full snapshot. Where TrackerSnapshot has trackerId, displayName, viewType, asOf, headline[] (top-of-page stat tiles), and one payload field per viewType:

viewType	Payload field	Per-item shape
table	rows[]	{rank, rowId, name, category?, url?, metrics[]} where each metric is {label, value, unit}

Live trackers as of this writing, all viewType: table. The catalog grows over time: treat the GET /api/v1/trackers discovery endpoint as the source of truth, not this table.

Tracker id	accessTier	What it ranks
reddit-picks	free	Stocks finance-Reddit turned bullish on, scored on return since entry vs SPY
institution-concentration	free	13F filers by share of the book held in their top 10 positions
institution-aum	free	Largest 13F filers by disclosed long-equity AUM
hedge-fund-reported-returns	pro	Net-of-fee annual returns large hedge funds publish, with citations
media-darlings	free	Stocks by how bullish or bearish the curated financial press is on them
sentiment-leaderboard	free	Most bullish and most bearish stocks by pure sentiment polarity
sentiment-movers	free	Biggest 7-day sentiment shifts, improving and deteriorating
trending-products	free	Products and services by mention volume and week-over-week growth

Column headers are the metric labels on rows[0]. Common metric unit values are percent, usd, and count; newer trackers add richer units such as polarity, ratio, status, and sparkline.

Errors: 404 unknown_tracker, 404 no_snapshot, 503 tracker_unavailable.

Methodology: https://sentisense.ai/methodology#institution-rankings.

---

Calendar API (/api/v1/calendar)

Forward-looking market calendars. Earnings is the first feed; the /calendar/{type} namespace is built to grow. The value is lead time: not what reports tonight, but which companies report over the next several weeks, with consensus EPS and confirmation status attached, so you can position ahead of the event. API key required on every call.

GET /api/v1/calendar

Discover which calendars are available. Discovery (no quota cost) -- API key required, does not burn monthly quota.

Response: { calendars: [ { type, path, description } ] }. Today: earnings.

GET /api/v1/calendar/earnings

Upcoming company earnings, sorted by date. Public (preview) -- Free: current week, PRO: full forward window (about 30 days). Field richness is identical across tiers; the gate is how far ahead you can see, not which columns you get. Defaults to the current week onward; pass an earlier from to include already-reported earnings.

Param	Type	Required	Default	Description
ticker	string	No	-	Filter to a single ticker
week	string	No	-	Shorthand window. this is the Monday-to-Sunday week containing the current US Eastern date; next is the seven days right after it. Rolls over at midnight ET, not local midnight; metadata.windowStart/windowEnd echo the resolved dates
from	string	No	-	Inclusive lower bound, ISO YYYY-MM-DD (overrides week)
to	string	No	-	Inclusive upper bound, ISO YYYY-MM-DD
confirmed	bool	No	-	When true, only company-confirmed dates
time	string	No	-	before_open, after_close, during_market, unknown

Response: { isPreview, previewReason, totalCount?, data: { earnings: [...], metadata: {...} } }. Each event: { ticker, companyName, earningsDate (ISO date), earningsTime, fiscalQuarter, confirmed, estimatedEps }. Metadata: { generatedAt (epoch seconds), windowStart, windowEnd, count, source }. On a FREE preview, totalCount is the full-window event count and data.earnings is limited to the current week.

earningsTime is always one of before_open, after_close, during_market, or unknown, never null or absent. Treat unknown as "no session claim applies" and render it as blank rather than as missing data. It covers two cases: timing the issuer has not published yet, and timing that cannot exist. A few issuers release results on a Saturday or Sunday ahead of a Monday call, and there is no weekend open or close for the report to sit against. A weekend earningsDate is legitimate data, not a bug. Do not drop it, and do not shift it to the next weekday; the date is what the issuer announced.

python

client = SentiSenseClient(api_key=os.environ["SENTISENSE_API_KEY"])
cal = client.get_earnings_calendar(week="next")
for e in cal.earnings:
    print(f"{e['earningsDate']} {e['ticker']} ({e['earningsTime']})")

---

Error Codes

Code	Meaning
200	Success
400	Bad request (missing/invalid parameters)
401	Unauthorized (invalid or missing API key)
403	Forbidden (insufficient tier)
404	Resource not found
429	Rate limit (rate_limit_exceeded, per-minute) response carries a Retry-After: 60 header; monthly quota (quota_exceeded) does NOT include Retry-After
500	Internal server error

---

Getting Started

1. Get a free API key at https://app.sentisense.ai/get-api-key (creates your account if you do not have one)
2. Start calling -- all you need is the API key in a header. No SDK install required:

bash

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/price?ticker=AAPL"

3. Upgrade to PRO ($15/mo) for full institutional flows, AI reports, politician data, and unlimited monthly requests: no monthly cap, just a 300/min rate. Apply coupon AGENTS26 at checkout for a builder launch discount: https://app.sentisense.ai/pricing?coupon=AGENTS26

SDKs (Optional Convenience)

SDKs are thin wrappers around the REST API. As an AI agent, you are encouraged to call endpoints directly with HTTP requests rather than installing packages. If you do want to use an SDK, review the source first:

Python: github.com/SentiSenseApp/sentisense (pip install sentisense)

python

import os
from sentisense import SentiSenseClient
client = SentiSenseClient(api_key=os.environ["SENTISENSE_API_KEY"])
price = client.get_stock_price("AAPL")

Node.js: github.com/SentiSenseApp/sentisense-node (npm install sentisense)

javascript

import SentiSense from 'sentisense';
const client = new SentiSense({ apiKey: process.env.SENTISENSE_API_KEY });
const price = await client.stocks.getPrice('AAPL');

---

Note: This skill file is updated frequently as new features ship. For the latest version, check sentisense.ai/skill.md.

SentiSense is a product of Compass AI Data Services, LLC. This data is for informational purposes only -- not investment advice.