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. Every endpoint requires an API key (free to generate in Settings > Developer Console); most are available in full on the Free tier.

---

Stock Lists & Metadata

GET /

Returns all available stock ticker symbols tracked by SentiSense.

Authentication: API key required | Parameters: None

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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: API key required | Parameters: None

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

Response object:

Field	Type	Description
ticker	string	Ticker symbol
name	string	Company name
kbEntityId	string	Ontology 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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/images?tickers=AAPL,TSLA,NVDA"

Response: Map<ticker, { iconUrl, logoUrl }>: URLs for company icons and logos. GET a URL directly to receive the image bytes; no API key is required for the image fetch itself, so the URLs can be used straight in an <img src> tag.

Treat these URLs as refreshable rather than permanent. Brand assets are periodically refreshed, and a URL issued for a previous revision stops resolving once that happens. Re-read them from this endpoint instead of storing them long term.

---

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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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 SentiSense ontology relationships.

Parameters:

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

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/AAPL/profile"

---

GET /{ticker}/entities

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

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

Response: array of related entities. Each entry:

Field	Type	Description
id	string	Internal KB entity ID
displayName	string	Entity display name
type	string	PERSON, PRODUCT, ORGANIZATION, etc.
relatedStock	string	The ticker you queried
urlSlug	string|null	Handle for the Metrics API {entityId} parameter (e.g. Tim-Cook)
title	string|null	Person's role (e.g. CEO)
category	string|null	Product category
appId	string|null	Apple App Store id when the product has a tracked companion app

---

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 429 with {error: "quota_exceeded", ...} when Free quota is exhausted, matching the platform-wide quota contract.

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: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/AAPL/ai-summary?depth=deep"

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

Field	Type	Description
ticker	string	Ticker symbol
companyName	string	Company name
status	string	READY, NOT_AVAILABLE, or ERROR
statusReason	string | 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	Map of section name to {content, directives}. Present on depth=deep only.
sectionOrder	string[]	Ordered section keys for rendering. Present on depth=deep only.
moatRating	integer | null	Proprietary moat quality score 0 to 10. null if not yet assessed for this ticker.
aiDisruptionRisk	string | null	Low, Medium, High, or Critical: AI revenue-displacement exposure. null if not yet assessed.

---

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	Yes	-	Start time (epoch ms)
endTime	long	Yes	-	End time (epoch ms)

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/AAPL/metrics/sentiment/breakdown?startTime=1745600000000&endTime=1746204800000"

---

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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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, 5Y, 10Y, MAX

Up to 26 years of split- and dividend-adjusted history. MAX returns a stock's full available
history, back to 1999 for names listed that long: 320 monthly bars for AAPL, versus the 5 years
most price APIs cap at. 10Y returns weekly bars over ten years.

Granularity is chosen per range so a long chart stays a sensible payload: intraday for 1D and
5D, daily through 1Y, weekly for 5Y and 10Y, monthly for MAX.

Ranges of 5Y and beyond are adjusted for both splits and dividends, so a long series is
comparable end to end rather than showing a cliff at every corporate action. Shorter ranges are
split-adjusted only. The two therefore differ slightly on the same historical date, by roughly the
dividends paid since: negligible for a non-payer, around 13% over five years for a 3% yielder.

202 Accepted on 10Y and MAX means that stock's deep history is still being assembled.
The body is an empty array and a Retry-After header gives the suggested wait in seconds; retry
and you will get the full series. We return this rather than silently substituting a shorter
range, so a 200 always means the range you asked for. It only happens on the first request for
a rarely-viewed stock.

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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/chart?ticker=AAPL&timeframe=6M"

---

GET /market-status

Returns the current US market status: open while the regular trading session is open, closed otherwise. Pre-market and after-hours report as closed.

Parameters: None

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

Response:

Field	Type	Description
status	string	open or closed
timestamp	long	When the status was computed (epoch milliseconds)

---

Fundamentals

Reporting currency. Statement figures are served as reported by the filer, in the
filer's own currency, and are never converted to US dollars. US filers report in USD, but
foreign filers listed as ADRs report in their home currency: SK hynix in KRW, Toyota in JPY,
ASML in EUR. Every fundamentals response (and each period row of /fundamentals/history)
carries an optional reportedCurrency field ("USD", "KRW", "EUR", ...) naming that currency.
When the field is absent, the currency is unknown, not implicitly USD.

Two practical consequences:

• Do not mix these figures with the share price. The listed price is the USD ADR price, so
  price ratios computed against non-USD figures are meaningless. For non-USD filers the API
  already suppresses peRatio, psRatio, and pbRatio to null for this reason.
• Same-currency ratios (margins, ROE, ROA, current ratio, debt/equity) remain valid for all
  filers, since numerator and denominator share the currency.

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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/fundamentals?ticker=AAPL&timeframe=quarterly"

---

GET /fundamentals/periods

Returns available fiscal periods for a stock.

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

---

GET /fundamentals/current

Returns the most recent fundamental data snapshot.

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

---

GET /fundamentals/history

Returns a multi-period history of full financial statements (income statement, balance sheet, and
cash flow), one entry per fiscal quarter or fiscal year, newest first. This is the endpoint behind
the statement tables on the Financials tab: use it for margin trends, multi-year comparisons, or as
the input data for a valuation model.

Not the same as /fundamentals (a single period) or /fundamentals/historical/revenue
(income-statement lines only, recent periods only): /fundamentals/history is the full
three-statement, multi-period table and the one to use for deep history.

Parameters:

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

The response echoes count (the number of periods actually returned, which can be lower than
limit on thin coverage). When no periods are available, periods is empty and reason explains
why (for example, a recent listing or an ETF/fund with no SEC filings). The dataSource field is
deprecated: it is always an empty string, kept only for response-shape compatibility, and will be
removed.

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/fundamentals/history?ticker=AAPL&timeframe=annual&limit=10"

---

GET /fundamentals/historical/revenue

Returns a lightweight income-statement series (revenue, gross profit, operating income, net
income, EPS) per fiscal quarter or year, wrapped in dataPoints with count and reason
(dataSource is deprecated and always empty). Covers recent periods only (roughly the last three
to four years). For longer history or the balance sheet and cash flow, use /fundamentals/history.

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/short-interest?ticker=AAPL"

---

GET /float

Returns float information (shares outstanding, public float).

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

---

GET /short-volume

Returns short volume trading data.

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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)
movingAverage200Day	number|null	200-day simple moving average of daily closes. null when fewer than 200 trading days of history exist (e.g. a recent IPO).
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,
  "movingAverage200Day": 198.42,
  "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.