Stocks API

Overview

The Stocks API provides comprehensive stock data including 15-minute-delayed 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"

Listing status: the profile also carries listingStatus, delistedDate and delistingReason when the symbol is delisted or pending delisting. All three are absent for a normally listed symbol, and they carry the same values as on GET /price: listingStatus is "DELISTED" or "PENDING_DELISTING", delistedDate is the ISO date trading stopped, and delistingReason is one of acquired, take_private, bankruptcy, exchange_rule, merged.

ETF profiles: when ticker identifies a tracked ETF, the response may also carry imageUrl, a square presentation image for the fund. It is the issuer's mark rather than the individual fund's, so every fund in a family shares one image, and it is the same value returned by the /etfs endpoints. It is square like logoUrl and iconUrl and drops into the same avatar slot, but it is a first-party asset rather than a vendor branding mark, so it is returned as a direct URL. It is absent for issuers we hold no image for.

---

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}/graph

Returns the typed relationships around one stock, including leaders, products and product families, peers, owners and subsidiaries, publishers, and topics.

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/AAPL/graph?depth=1&cap=75"

Parameters:

Parameter	Type	Required	Default	Description
depth	integer	No	1	Traversal depth, either 1 or 2
cap	integer	No	75	Maximum non-root nodes, from 1 to 200

Response: a bounded graph projection with the requested stock as its root.

Field	Type	Description
ticker	string	Uppercase ticker symbol
root	string	Slug of the root company; matches one entry in nodes
depth	integer	Applied traversal depth
cap	integer	Applied non-root node cap
truncated	boolean	true when more matching nodes exist beyond cap
omitted	integer	Nodes left out because they carry no slug, and so cannot be addressed
counts	object	Returned nodes, edges, and node totals in byType
groups	object	Slugs grouped as people, products, productFamilies, peers, organizations, publishers, and topics
nodes[]	array	Nodes with slug, displayName, and type
edges[]	array	Relationships with source, target, type, direction, and properties

{
  "ticker": "AAPL",
  "root": "Apple-Inc",
  "depth": 1,
  "cap": 75,
  "truncated": false,
  "omitted": 0,
  "counts": {
    "nodes": 2,
    "edges": 1,
    "byType": { "COMPANY": 1, "PERSON": 1 }
  },
  "groups": {
    "people": ["Tim-Cook"],
    "products": [],
    "productFamilies": [],
    "peers": [],
    "organizations": [],
    "publishers": [],
    "topics": []
  },
  "nodes": [
    { "slug": "Apple-Inc", "displayName": "Apple Inc.", "type": "COMPANY" },
    { "slug": "Tim-Cook", "displayName": "Tim Cook", "type": "PERSON" }
  ],
  "edges": [
    { "source": "Tim-Cook", "target": "Apple-Inc", "type": "LEADS", "direction": "DIRECTED", "properties": {} }
  ]
}

Handles: slugs are the only identifier here. The same string does three jobs: it joins groups and edges to nodes inside one response, it addresses the entity on the Metrics API and Documents API, and it is the entity page path (/entities/Tim-Cook). A product family is { "family": "iPhone", "members": ["iPhone-15"] }, slugs on both sides.

Edge types: OWNS, PEER, BELONGS_TO, LEADS, FOUNDED, AFFILIATED_WITH, VARIANT_OF, SUBTOPIC_OF, and SUBSIDIARY_OF are curated relationships. PRODUCT_OF is derived from a product's associated company.

Direction: DIRECTED preserves the relationship from source to target. BIDIRECTIONAL combines matching relationships present in both directions.

Unknown ticker: returns 404 with error: "entity_not_found" and up to three suggestions from entity search.

Free with an API key; rate limits apply. One ticker per call; there is no enumeration endpoint.

---

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

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 both depths. depth=basic returns a single Executive Summary section; depth=deep returns the full set.
sectionOrder	string[]	Ordered section keys for rendering. Present on both depths. ["Executive Summary"] on depth=basic.
moatRating	integer | null	Proprietary moat quality score 0 to 10. Present on depth=deep only. null if not yet assessed for this ticker.
aiDisruptionRisk	string | null	Low, Medium, High, or Critical: AI revenue-displacement exposure. Present on depth=deep only. null if not yet assessed.

Do not branch on the presence of sections to decide whether you received a deep report: both depths return it. Read reportType (SUMMARY vs FULL), or check the length of sectionOrder.

---

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 latest price for a single stock ticker, delayed 15 minutes.

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, delayed 15 minutes. During RTH (09:30 to 16:00 ET): the most recent regular-session value. 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	When this response was served (epoch milliseconds). Not the age of the price: it tracks the current clock regardless of how old the value is.
priceAsOf	long | absent	When the market data behind currentPrice is from (epoch milliseconds). This is the field to read for freshness. Omitted outside regular hours, and whenever the upstream data is not dated, so treat its absence as "unknown" rather than "fresh".
extendedHours	object | null	Extended-hours view (pre-market or after-hours). Absent during RTH, overnight, and weekends. See below.
listingStatus	string | absent	"DELISTED" or "PENDING_DELISTING". Present only when the symbol is delisted or pending delisting, absent otherwise.
delistedDate	string | absent	ISO date (YYYY-MM-DD) trading stopped. Present only alongside listingStatus: "DELISTED".
delistingReason	string | absent	One of acquired, take_private, bankruptcy, exchange_rule, merged. Present only alongside listingStatus: "DELISTED".

Delisted symbols return their last trade price rather than an error, and listingStatus is what marks that price as frozen. On a "DELISTED" symbol, currentPrice, change and changePercent never advance again. Nothing else in the payload says so, so read listingStatus before rendering a price as current.

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 the latest prices for multiple tickers in a single request, delayed 15 minutes (see /price above).

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, an optional extendedHours object during pre/post sessions, and the optional listingStatus / delistedDate / delistingReason fields. Check each element for a frozen price rather than assuming a batch is uniformly live. 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
through 1M (5-minute for 1D, 15-minute for 5D, 30-minute for 1W, hourly for 1M), daily
for 3M through 1Y, weekly for 5Y and 10Y, monthly for MAX.

Ranges of 10Y and MAX 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,
including 5Y, are split-adjusted only. The two bases therefore differ on the same historical
date, by roughly the dividends paid since: negligible for a non-payer, around 14% over five years
for a 3% yielder. volume is restated to today's share count in every range, so a pre-split bar
reports shares on the current basis and the volume series has no cliff either. Only splits move
it: a dividend changes the price basis but not the number of shares that changed hands.

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.

A timeframe value outside the list above answers 400 Bad Request with an invalid_timeframe
error naming the valid values.

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, weekly, and monthly 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"

Migrating from an internal chart endpoint on another site? GET /chart is the documented
equivalent, with full OHLCV bars instead of close-only pairs. Field-by-field mapping:
the migration guide.

---

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).
In responses, fiscalYear is a string.

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.

Key on periodEndDate: it is unique per ticker and timeframe, never null, and rows are sorted by it newest first. fiscalYear follows the filer's naming convention and may
differ from the calendar year of the period end: Lululemon's year ending 2025-02-02 is fiscal 2024.

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 the latest price (delayed 15 minutes), 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, delayed 15 minutes. During RTH (09:30 to 16:00 ET): the most recent regular-session value. 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).
reportedCurrency	string|null	Currency epsTTM is reported in ("USD", "EUR", "KRW", ...), as filed. Same field and same meaning as on the fundamentals endpoints. Absent when no fundamentals are available for the ticker.
timestamp	number|null	When this response was served (epoch milliseconds). Not the age of the price: it tracks the current clock regardless of how old the value is.
priceAsOf	number | absent	When the market data behind currentPrice is from (epoch milliseconds). This is the field to read for freshness. Omitted outside regular hours, and whenever the upstream data is not dated, so treat its absence as "unknown" rather than "fresh".
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 }.
listingStatus	string | absent	"DELISTED" or "PENDING_DELISTING". Present only when the symbol is delisted or pending delisting, absent otherwise.
delistedDate	string | absent	ISO date (YYYY-MM-DD) trading stopped. Present only alongside listingStatus: "DELISTED".
delistingReason	string | absent	One of acquired, take_private, bankruptcy, exchange_rule, merged. Present only alongside listingStatus: "DELISTED".

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

Null fields are omitted from the JSON. A null field is left out of the response body entirely rather than serialized as null, so the key count varies by ticker. Read defensively rather than assuming a key is present.

Foreign filers omit reportedCurrency, epsTTM and peRatio. On foreign ADR filers such as ASML and TM those three fields are absent, while price fields, marketCap and dividendYield are served normally. This is the same cross-currency rule the fundamentals endpoints follow: currentPrice is the USD ADR price and the filer's earnings are in home currency, so a trailing P/E would mix two currencies. We withhold it rather than publish a wrong number. Do not fill the gap by dividing currentPrice by a non-USD epsTTM.

Delisted symbols keep quoting their last trade. When listingStatus reads "DELISTED", every price field above is frozen at the last trade before delistedDate and nothing else in the response says so. The same three fields appear on GET /price and GET /{ticker}/profile.

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,
  "reportedCurrency": "USD",
  "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. The error body also carries a seeInstead array holding that exact path, so a client can follow it without string-matching the message:

{
  "error": "ticker_is_etf",
  "message": "SPY is an ETF; use /api/v1/etfs/SPY/quote",
  "seeInstead": ["/api/v1/etfs/SPY/quote"]
}

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

---

Company KPIs

A KPI is a per-company key performance indicator series: the operating numbers a company reports about itself, quarter after quarter, in a chartable shape. Financial statements describe what every company reports; KPIs describe what a specific company reports. The set covers GAAP line items and the company-specific non-GAAP metrics that move a stock, such as iPhone unit sales, Tesla deliveries, AWS revenue, and Netflix paid net adds. Every series is curated per company from earnings filings and press releases, and carries a citation to the filing it came from.

The endpoints below cover the whole surface: GET /with-kpis enumerates coverage, GET /{ticker}/kpis/types lists one company's metrics, and GET /{ticker}/kpis returns the series. The reference for each follows this section.

The three-step KPI workflow

Discovery first, then metadata, then data. Steps 1 and 2 are Discovery tier: an API key is required for identity, but neither call consumes monthly quota, so a client can refresh the shape of its universe far more often than it fetches series payloads. Only step 3 is quota-gated and PRO-gated.

Step 1: discover which companies have coverage. Call once at startup and cache it. Enumerating coverage is the supported alternative to probing tickers one at a time and collecting 404s.

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

{
  "count": 947,
  "tickers": [
    { "ticker": "AAPL", "companyName": "Apple Inc.", "lastUpdated": "2026-01-30", "kpiCount": 8 },
    { "ticker": "ABBV", "companyName": "AbbVie Inc.", "lastUpdated": "2026-01-25", "kpiCount": 6 }
  ]
}

Step 2: list one company's KPI types. Metadata tuples only, with no series payload attached. Use it to decide what is worth rendering, or to let an agent choose, before committing to the heavy call.

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

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

Step 3: fetch the series. The endpoint takes only the ticker and returns every curated series for it; select the ones you need by id from Step 2. Points are ordered newest to oldest: the first element is the most recently reported period.

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

{
  "isPreview": false,
  "previewReason": null,
  "data": {
    "ticker": "AAPL",
    "companyName": "Apple Inc.",
    "cik": "0000320193",
    "lastUpdated": "2026-01-30",
    "kpis": [
      {
        "id": "iphone_revenue",
        "name": "iPhone Revenue",
        "category": "product_revenue",
        "unit": "USD",
        "displayFormat": "currency_abbreviated",
        "chartType": "bar",
        "values": [
          { "period": "Q4 FY2025", "date": "2025-09-27", "value": 50000000000, "isEstimate": null },
          { "period": "Q1 FY2026", "date": "2025-12-27", "value": 85000000000, "isEstimate": null }
        ],
        "sourceRef": "Apple 8-K Q1 FY2026 press release",
        "discontinued": false,
        "discontinuedNote": null
      }
    ]
  }
}

Example values throughout this section are illustrative, not live readings.

---

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: API key required on every call; PRO for the series data. A free key receives isPreview: true with the company metadata and an empty kpis list, which is enough to detect coverage and gate the UI. Calls without a key return 401 api_key_required.

Parameters:

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

Coverage today: near-complete for the S&P 500 plus an extended universe of 900+ tickers, and growing. Entries can briefly show kpiCount: 0 while curation for a newly added company is in flight; skip those when enumerating. 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
upgrade	object	Present only when isPreview is true. Carries plan, message, price, url and relay: surface message and url to your user in one line, then continue with the preview data
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, newest to oldest (first element is most recent)
sourceRef	string	Citation for the source filing
discontinued	boolean or null	true when the company has stopped reporting this metric; null or false otherwise
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": 947,
  "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.

---

Reading a KPI point

Periods are fiscal, not calendar. period is a display label such as "Q1 FY2026"; date is the ISO date on which that period closed. The two routinely disagree with the calendar: a fiscal Q1 can close in December. Sort and align on date, label with period, and do not assume a fiscal quarter maps to a calendar quarter when comparing two companies.

Units live on the series, not on the point. value is a raw number. Its meaning comes from unit on the parent series ("USD", "units", "subscribers", "%"), and displayFormat is the matching rendering hint (currency_abbreviated, number_abbreviated, percent). Read the two together rather than inferring a unit from the series name. chartType carries the intended default rendering, bar or line.

Points run newest to oldest. The first element is the most recently reported period, so a sequential delta is the first two elements, and a year-over-year delta is the first element against the one four positions later (index 0 against index 4) when the series has no gaps. Series lengths vary by company and metric; check the length before indexing.

Two flags change how a series should be displayed. isEstimate is true for a preliminary or estimated value and is usually null otherwise. discontinued is true once a company stops reporting a metric, with an optional discontinuedNote; a discontinued series remains valid history but should not sit on a live dashboard as though a new print is coming.

Every series carries sourceRef, a citation for the filing the numbers came from. Surface it wherever a user might ask where a number originated.

Dual-class tickers resolve server-side. KPI endpoints accept the secondary share class and resolve it to the curated primary, so GOOG reaches Alphabet's series and BRK-B reaches Berkshire's. See Ticker symbols for the aliasing rules, including the pairs that are tracked separately rather than aliased.

Patterns for builders

Quarter-over-quarter and year-over-year deltas. The series arrives ordered newest first, so deltas are arithmetic rather than an extra request: the first two points for the sequential move, the first against the point four positions later for the annual move. Ranking a watchlist by acceleration in a company-specific metric surfaces moves that a price screen does not.

Earnings-eve reads. Combine GET /api/v1/calendar/earnings with a watchlist to find which companies report next, then load their KPI series to show which operating numbers matter and how they have trended into the print. Because coverage discovery and KPI types cost no monthly quota, the watchlist intersection can refresh far more often than the series fetch.

Pairing KPIs with sentiment. Fetch the reported operating number from the KPI endpoints and the market's reading from GET /api/v2/metrics/entity/{entityId}/metric/{metricType}, where metricType is mentions, sentiment, sentisense, or social_dominance. Metric points are time-ascending with a flat value scalar, so they plot directly against a KPI series. A core metric accelerating while sentiment fades, or the reverse, is a divergence a price chart does not show.

Cache by reporting cadence. Most KPI series change only when a company files, which for the majority of metrics means once a quarter. Cache the coverage list and the type list on a daily cadence, and refresh a company's series around its reporting date rather than on every page view. lastUpdated on both the coverage entry and the series payload tells you when a refresh actually landed.

---

Sentiment

GET /{ticker}/sentiment

Returns the stock's headline sentiment picture in one call: the proprietary SentiSense Score, its
30-day regime and direction, a daily sparkline, where the conversation is happening by source, the
stories driving it, and curated peer tickers.

This is the endpoint the Developer Console hands you as your first call.

Authentication: API key required. Available in full on the Free 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/sentiment"

When there is nothing to return: a 404 whose error is either entity_not_found (no stock is tracked under that symbol; the body carries up to three suggestions, so resolve with GET /api/v1/kb/entities/search?q= and retry) or no_coverage (the symbol is tracked, we hold no sentiment record for it, and a different spelling will not help). See Two kinds of 404.

Response Schema:

Field	Type	Description
ticker	string	Ticker symbol
companyName	string	Company name
asOf	string	ISO date (YYYY-MM-DD) the data is current as of
sentisenseScore	number or null	Today's SentiSense Score (sentiment x mentions composite, unbounded). Null until today's reading lands, see the note below
sentisenseScoreAvg30d	number	30-day average Score, the stable regime figure
sentisenseScoreDelta30d	number	Change in the Score over 30 days
scoreLabel	string	Seven-band label of the 30-day average
direction	string	"Bullish", "Neutral" or "Bearish", from the 30-day average
latestDirection	string or null	Same three bands, from today's read. Null in lockstep with sentisenseScore
trend	string	"UP", "DOWN" or "FLAT"
scoreSparkline	number[]	Daily Score series
mentions	number	Today's mention volume
mentionsAvg30d	number	30-day average mentions per day
socialDominance	number	Latest share of voice, as a fraction (0.021 = 2.1%)
bySource[]	array	Per-source tone, loudest source first: source, direction, mentionShare (whole-number percent, the array sums to 100), value (exact polarity, -1 to 1)
relatedTickers[]	array	Curated peer tickers: ticker, name
drivers[]	array	Top story drivers: title, tone (-1 to 1)
narrative	string	Short plain-language summary of why the Score sits where it does
faq[]	array	Question and answer pairs covering the common asks for this ticker

sentisenseScore and latestDirection are today's reading, and are null until the day's first analytics run lands (mid-morning ET, later at weekends). Poll before that and every ticker returns null for these two, which is a timing state and not an outage. The rest of the response is unaffected: scoreLabel, direction and sentisenseScoreAvg30d are all computed from the 30-day average, so prefer those when you need a headline that is always present. A null here means "no reading yet", never a Score of zero. A measured 0.0 is served as 0.0, so do not coerce null to 0, and do not infer absence by thresholding the 30-day average, which would suppress genuine neutrals.

Example Response:

{
  "ticker": "AAPL",
  "companyName": "Apple Inc.",
  "asOf": "2026-08-02",
  "sentisenseScore": 41.2,
  "sentisenseScoreAvg30d": 33.8,
  "sentisenseScoreDelta30d": 7.4,
  "scoreLabel": "Moderately Positive",
  "direction": "Bullish",
  "latestDirection": "Bullish",
  "trend": "UP",
  "scoreSparkline": [28.1, 30.4, 31.9, 35.2, 41.2],
  "mentions": 1840,
  "mentionsAvg30d": 1512,
  "socialDominance": 0.081,
  "bySource": [
    { "source": "News",   "direction": "Bullish", "mentionShare": 58, "value": 0.1889 },
    { "source": "Reddit", "direction": "Neutral", "mentionShare": 21, "value": 0.0428 },
    { "source": "X",      "direction": "Bullish", "mentionShare": 10, "value": 0.1809 }
  ],
  "relatedTickers": [ { "ticker": "MSFT", "name": "Microsoft Corporation" } ],
  "drivers": [ { "title": "Apple raises services guidance", "tone": 0.44 } ],
  "narrative": "Sentiment has strengthened over the past month, led by news coverage.",
  "faq": [ { "question": "Is AAPL bullish or bearish?", "answer": "..." } ]
}

Returns 404 Not Found when the ticker has no sentiment coverage.

This is the single-stock read. Two market-wide counterparts live in the Market Mood API: /api/v1/sentiment/sectors ranks the 11 GICS sectors against the market's own tone, and /api/v1/sentiment/breadth gives the bullish/neutral/bearish share of the roughly 1,000 covered stocks, the sentiment analogue of an advance/decline line.

Note on the response envelope: search-engine crawlers receive the same document with the exact
per-source value omitted; direction and mention share are always present. API-key callers on any
tier receive the full payload.