--- slug: "sentisense-x-3" source_type: "clawhub" source_url: "https://clawhub.ai/skills/sentisense" repo: "" source_file: "description" --- --- name: sentisense description: "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." homepage: https://sentisense.ai requires: env: - SENTISENSE_API_KEY primaryEnv: SENTISENSE_API_KEY metadata: openclaw: requires: env: - SENTISENSE_API_KEY primaryEnv: SENTISENSE_API_KEY --- # 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](https://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](https://github.com/SentiSenseApp/sentisense) | [Node.js](https://github.com/SentiSenseApp/sentisense-node) -- 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](https://sentisense.ai/agreement/API-Terms-of-Service.pdf) and [Terms of Service](https://sentisense.ai/agreement/Terms-of-Service.pdf). --- ## 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](https://app.sentisense.ai/settings/developer)). ### 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: }`. 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: ``` 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](https://sentisense.ai/agreement/API-Terms-of-Service.pdf). ### 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: . ### 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: ``` {"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:** . --- ## 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](https://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](https://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](https://sentisense.ai/skill.md). *SentiSense is a product of Compass AI Data Services, LLC. This data is for informational purposes only -- not investment advice.*