Stocks API

Overview

The Stocks API provides comprehensive stock data including real-time prices, historical charts, company fundamentals, short interest metrics, and AI-powered analysis reports. Most endpoints are publicly accessible without authentication.

---

Stock Lists & Metadata

GET /

Returns all available stock ticker symbols tracked by SentiSense.

Authentication: None required | Parameters: None

curl "https://app.sentisense.ai/api/v1/stocks"

Response: string[] (e.g., ["AAPL", "MSFT", "GOOGL", ...])

---

GET /detailed

Returns all stocks with company name, KB entity ID, and URL slug.

Authentication: None required | Parameters: None

curl "https://app.sentisense.ai/api/v1/stocks/detailed"

Response object:

Field	Type	Description
ticker	string	Ticker symbol
name	string	Company name
kbEntityId	string	Knowledge base entity ID
urlSlug	string	URL-friendly slug
socialDominance	object | null	Precomputed share of voice. value is share as a 0-1 decimal, rank is 1-based across the coverage universe, percentile is 0-100. Null when no signal exists. Refreshed daily.

---

GET /popular

Returns popular stock tickers. Parameters: None

curl "https://app.sentisense.ai/api/v1/stocks/popular"

Response: string[]

---

GET /popular/detailed

Returns popular stocks with company details. Same schema as /detailed.

---

GET /images

Returns company logo/icon URLs for a batch of tickers.

Parameters:

Parameter	Type	Required	Default	Description
tickers	string	Yes	-	Comma-separated tickers (max 600)
forced	boolean	No	false	Bypass cache

curl "https://app.sentisense.ai/api/v1/stocks/images?tickers=AAPL,TSLA,NVDA"

Response: Map<ticker, { iconUrl, logoUrl }> — URLs for company icons and logos.

---

GET /descriptions

Returns company profiles with branding, market cap, and sector information.

Parameters:

Parameter	Type	Required	Default	Description
tickers	string	Yes	-	Comma-separated tickers
forced	boolean	No	false	Bypass cache

curl "https://app.sentisense.ai/api/v1/stocks/descriptions?tickers=AAPL,MSFT"

---

Per-Stock Data

GET /{ticker}/similar

Returns peer and similar stocks based on sector, industry, and knowledge graph relationships.

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol
limit	integer	No	5	Max results

curl "https://app.sentisense.ai/api/v1/stocks/AAPL/similar?limit=10"

---

GET /{ticker}/profile

Returns a company profile including CEO, sector, industry, and market data.

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol
forced	boolean	No	false	Bypass cache

curl "https://app.sentisense.ai/api/v1/stocks/AAPL/profile"

---

GET /{ticker}/entities

Returns knowledge base entities related to a stock (e.g., CEO, key products, partner companies).

curl "https://app.sentisense.ai/api/v1/stocks/AAPL/entities"

---

GET /{ticker}/ai-summary

Returns an AI-generated stock analysis report. PRO feature with limited Free access: depth=basic returns a preheader summary (Free: unlimited). depth=deep returns a full multi-section report (Free: 10 views/month, PRO: unlimited). Returns 402 when Free quota is exhausted.

Authentication: API key required

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol
depth	string	No	basic	Analysis depth: basic or deep
forceRefresh	boolean	No	false	Generate fresh report

curl -H "X-SentiSense-API-Key: ssk_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/AAPL/ai-summary?depth=deep"

---

GET /{ticker}/metrics/{metricType}/breakdown

Returns sentiment or mention metrics broken down by entity for a stock over a time range.

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker
metricType	path	Yes	-	Metric type (e.g., sentiment, mentions)
startTime	long	No	-	Start time (epoch ms)
endTime	long	No	-	End time (epoch ms)

curl "https://app.sentisense.ai/api/v1/stocks/AAPL/metrics/sentiment/breakdown"

---

Market Data & Prices

GET /price

Returns the real-time price for a single stock ticker.

Parameters:

Parameter	Type	Required	Default	Description
ticker	string	Yes	-	Stock ticker symbol

curl "https://app.sentisense.ai/api/v1/stocks/price?ticker=AAPL"

Response:

Field	Type	Description
ticker	string	Ticker symbol
currentPrice	double	Regular-session price. During RTH (09:30 to 16:00 ET): live last trade. Otherwise: most recent regular-session close.
change	double	currentPrice change vs previousClose
changePercent	double	currentPrice change percentage
previousClose	double	Previous closing price
volume	long	Volume
timestamp	long	Price timestamp
extendedHours	object | null	Extended-hours view (pre-market or after-hours). Absent during RTH, overnight, and weekends. See below.

extendedHours object:

Field	Type	Description
session	string	"pre" (04:00 to 09:30 ET) or "post" (16:00 to 20:00 ET)
price	double	Live extended-hours price
change	double	Extended-hours price change vs currentPrice
changePercent	double	Extended-hours change percentage vs currentPrice

---

GET /prices

Returns real-time prices for multiple tickers in a single request.

Parameters:

Parameter	Type	Required	Default	Description
tickers	string	Yes	-	Comma-separated tickers

curl "https://app.sentisense.ai/api/v1/stocks/prices?tickers=AAPL,TSLA,NVDA"

Response: StockPrice[] (JSON array). Each element is the same price object as /price, including a ticker field identifying the symbol and an optional extendedHours object during pre/post sessions. Tickers that fail to resolve are silently omitted from the array.

---

GET /chart

Returns historical OHLCV (Open, High, Low, Close, Volume) chart data for a stock.

Parameters:

Parameter	Type	Required	Default	Description
ticker	string	Yes	-	Stock ticker symbol
timeframe	string	No	1M	Chart timeframe: 1D, 5D, 1W, 1M, 3M, 6M, 1Y, ALL

Response: array of bars. Each bar has:

Field	Type	Description
timestamp	long	Unix timestamp in milliseconds
date	string	Pre-formatted display string (format varies by timeframe)
open	double	Opening price
high	double	Highest price during the bar
low	double	Lowest price during the bar
close	double	Closing price
volume	long	Bar volume
session	string | null	US-equity session: pre (04:00 to 09:30 ET), regular (09:30 to 16:00 ET), or post (16:00 to 20:00 ET). Populated for intraday timeframes (1D, 5D, 1W, 1M); null for daily and weekly bars (3M and longer) that span whole sessions. The 1M timeframe returns regular-session bars only.

curl "https://app.sentisense.ai/api/v1/stocks/chart?ticker=AAPL&timeframe=6M"

---

GET /market-status

Returns the current market status (open, closed, pre-market, after-hours).

Parameters: None

curl "https://app.sentisense.ai/api/v1/stocks/market-status"

---

Fundamentals

GET /fundamentals

Returns financial statement data for a stock (income statement, balance sheet, cash flow).

Parameters:

Parameter	Type	Required	Default	Description
ticker	string	Yes	-	Stock ticker
timeframe	string	No	quarterly	quarterly or annual
fiscalPeriod	string	No	-	Specific period (e.g., Q4)
fiscalYear	integer	No	-	Specific year (e.g., 2024)

curl "https://app.sentisense.ai/api/v1/stocks/fundamentals?ticker=AAPL&timeframe=quarterly"

---

GET /fundamentals/periods

Returns available fiscal periods for a stock.

curl "https://app.sentisense.ai/api/v1/stocks/fundamentals/periods?ticker=AAPL"

---

GET /fundamentals/current

Returns the most recent fundamental data snapshot.

curl "https://app.sentisense.ai/api/v1/stocks/fundamentals/current?ticker=AAPL"

---

GET /fundamentals/historical/revenue

Returns historical quarterly/annual revenue data.

curl "https://app.sentisense.ai/api/v1/stocks/fundamentals/historical/revenue?ticker=AAPL"

---

Short Interest & Float

GET /short-interest

Returns short interest data from FINRA for a stock.

curl "https://app.sentisense.ai/api/v1/stocks/short-interest?ticker=AAPL"

---

GET /float

Returns float information (shares outstanding, public float).

curl "https://app.sentisense.ai/api/v1/stocks/float?ticker=AAPL"

---

GET /short-volume

Returns short volume trading data.

curl "https://app.sentisense.ai/api/v1/stocks/short-volume?ticker=AAPL"

---

Quote Snapshot

GET /{ticker}/quote

Returns a single-call aggregate snapshot combining live price, today's OHLC, 52-week range, market cap, and key fundamentals. Designed for detail pages that need all key stats in one request.

Authentication: API key required | Rate limit: standard quota

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

Response object:

Field	Type	Description
ticker	string	Ticker symbol
currentPrice	number|null	Regular-session price. During RTH (09:30 to 16:00 ET): live last trade. Otherwise: most recent regular-session close.
change	number|null	currentPrice change vs previousClose
changePercent	number|null	currentPrice change percentage vs previousClose
volume	number|null	Volume for the current session
open	number|null	Opening price for the current session
dayHigh	number|null	Intraday high
dayLow	number|null	Intraday low
previousClose	number|null	Previous session close
week52High	number|null	52-week high
week52Low	number|null	52-week low
marketCap	number|null	Market capitalization (USD)
peRatio	number|null	Trailing P/E ratio
epsTTM	number|null	Earnings per share (TTM)
dividendYield	number|null	Annual dividend yield (decimal, e.g. 0.005)
timestamp	number|null	Quote timestamp (epoch milliseconds)
extendedHours	object | null	Extended-hours view (pre-market or after-hours). Absent during RTH, overnight, and weekends. Same shape as on /price: { session, price, change, changePercent }.

All fields except ticker are nullable. Render "--" or hide the row when a field is absent.

Example response (after-hours):

{
  "ticker": "AAPL",
  "currentPrice": 213.45,
  "change": 1.23,
  "changePercent": 0.58,
  "volume": 48203100,
  "open": 212.10,
  "dayHigh": 214.20,
  "dayLow": 211.80,
  "previousClose": 212.22,
  "week52High": 237.23,
  "week52Low": 164.08,
  "marketCap": 3280000000000,
  "peRatio": 32.1,
  "epsTTM": 6.65,
  "dividendYield": 0.0044,
  "timestamp": 1745600000000,
  "extendedHours": {
    "session": "post",
    "price": 214.10,
    "change": 0.65,
    "changePercent": 0.30
  }
}

ETF tickers: This endpoint is stock-only. Calling it with an ETF ticker (e.g. VTI, SPY) returns 400 ticker_is_etf with a pointer to GET /etfs/{ticker}/quote which returns AUM, expense ratio, NAV, and inception date instead of market cap / P/E / EPS.

Rate-limit note: Cached for 15 seconds server-side. Each call still counts toward your monthly quota.

---

GET /{ticker}/kpis

Returns company-specific KPI time-series for a ticker. KPIs are curated GAAP and non-GAAP metrics extracted from earnings filings and press releases (e.g. iPhone unit sales, Tesla deliveries, AWS revenue, Netflix paid net adds).

Authentication: PRO required. Free and unauthenticated users receive metadata only with an empty kpis list, which is enough to detect coverage and gate the UI.

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol

Coverage today: near-complete for the S&P 500 plus extended universe (~500 tickers). Roadmap: coverage extending to the long-tail of US tickers; some tickers may return 404 Not Found until curated. Use GET /with-kpis to enumerate the current set.

Example Request:

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

Response Schema (envelope):

Field	Type	Description
isPreview	boolean	true when the caller is on the FREE tier
previewReason	string	"PRO_REQUIRED" or null
data.ticker	string	Stock ticker
data.companyName	string	Company name
data.cik	string	SEC Central Index Key (when available)
data.lastUpdated	string	ISO date of the last KPI refresh
data.kpis	array of KpiSeries	Time-series objects (PRO only; empty in preview)

KpiSeries object:

Field	Type	Description
id	string	Stable per-ticker identifier, e.g. "iphone_revenue"
name	string	Human-readable name, e.g. "iPhone Revenue"
category	string	Logical category: "product_revenue", "segment_revenue", "unit_economics", etc.
unit	string	Unit of measurement: "USD", "units", "subscribers", "%", etc.
displayFormat	string	Display hint: "currency_abbreviated", "number_abbreviated", "percent", etc.
chartType	string	Default chart type: "bar" or "line"
values	array of KpiDataPoint	Time-series data points, oldest to newest
sourceRef	string	Citation for the source filing
discontinued	boolean	true when the company has stopped reporting this metric
discontinuedNote	string	Optional human-readable note about discontinuation

KpiDataPoint object:

Field	Type	Description
period	string	Fiscal period label, e.g. "Q2 FY2026"
date	string	ISO date of the period close, e.g. "2025-12-27"
value	number	Numeric value for the period
isEstimate	boolean|null	true for preliminary or estimated values; usually null

Example Response (truncated):

{
  "isPreview": false,
  "previewReason": null,
  "data": {
    "ticker": "AAPL",
    "companyName": "Apple Inc.",
    "cik": "0000320193",
    "lastUpdated": "2026-04-30",
    "kpis": [
      {
        "id": "iphone_revenue",
        "name": "iPhone Revenue",
        "category": "product_revenue",
        "unit": "USD",
        "displayFormat": "currency_abbreviated",
        "chartType": "bar",
        "values": [
          { "period": "Q1 FY2025", "date": "2024-12-28", "value": 69702000000, "isEstimate": null },
          { "period": "Q2 FY2025", "date": "2025-03-29", "value": 46841000000, "isEstimate": null },
          { "period": "Q3 FY2025", "date": "2025-06-28", "value": 39286000000, "isEstimate": null },
          { "period": "Q4 FY2025", "date": "2025-09-27", "value": 49025000000, "isEstimate": null },
          { "period": "Q1 FY2026", "date": "2025-12-27", "value": 85269000000, "isEstimate": null }
        ],
        "sourceRef": "Apple 8-K Q1 FY2026 press release",
        "discontinued": false,
        "discontinuedNote": null
      }
    ]
  }
}

---

GET /with-kpis

Lists every ticker with curated KPI coverage, sorted alphabetically. Builder discovery use case: render a supported-tickers page or seed a watchlist without 404-probing one ticker at a time.

Authentication: API key required. No monthly quota cost (Discovery tier: the call registers identity for abuse tracking but does not burn the per-month quota; rate-limit-per-minute still applies).

Parameters: None.

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/with-kpis"

Response Schema:

Field	Type	Description
count	int	Total number of tickers with curated KPI coverage
tickers	array of KpiCoverageEntry	Listing sorted alphabetically by ticker

KpiCoverageEntry object:

Field	Type	Description
ticker	string	Stock ticker
companyName	string	Company name
lastUpdated	string	ISO date of the last KPI refresh for this ticker
kpiCount	int	Number of distinct KPI series available for this ticker

Example Response (truncated):

{
  "count": 466,
  "tickers": [
    { "ticker": "A",    "companyName": "Agilent Technologies, Inc.", "lastUpdated": "2026-04-12", "kpiCount": 5 },
    { "ticker": "AAPL", "companyName": "Apple Inc.",                 "lastUpdated": "2026-04-30", "kpiCount": 8 },
    { "ticker": "ABBV", "companyName": "AbbVie Inc.",                "lastUpdated": "2026-04-22", "kpiCount": 6 }
  ]
}

---

GET /{ticker}/kpis/types

Lists the KPI metadata tuples available for a ticker without paying the cost of the full series payload. Mirrors the /api/v1/insights/stock/{ticker}/types precedent. Useful for letting an agent or UI decide which KPIs to render before fetching the data.

Authentication: API key required. No monthly quota cost (Discovery tier).

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol

Example Request:

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

Response Schema (bare array):

Field	Type	Description
id	string	Stable per-ticker identifier
name	string	Human-readable name
category	string	Logical category
chartType	string	Default chart type: "bar" or "line"

Example Response:

[
  { "id": "iphone_revenue",   "name": "iPhone Revenue",   "category": "product_revenue", "chartType": "bar"  },
  { "id": "services_revenue", "name": "Services Revenue", "category": "segment_revenue", "chartType": "line" },
  { "id": "mac_revenue",      "name": "Mac Revenue",      "category": "product_revenue", "chartType": "bar"  }
]

Returns 404 Not Found when the ticker has no curated KPIs.