Analyst Ratings API

Overview

The Analyst Ratings API provides programmatic access to Wall Street analyst coverage data: aggregate price target bands, the buy/hold/sell distribution, recent upgrade and downgrade actions, and forward EPS estimates with earnings surprise history.

Use cases:

• Pull the consensus price target and upside-to-current for any covered ticker
• Track the rate and direction of analyst revisions on a stock or across the market
• Compare actual EPS prints against the consensus estimate (earnings surprise tracking)
• Cross-reference analyst signals with insider trading, institutional flows, and AI insights

Free preview: the price target band (targetLow, targetMean, targetHigh, numberOfAnalysts, consensusLabel) is returned in full to free users. The buy/hold/sell distribution counts are PRO-only. The actions feed is limited to the 3 most recent rows for free, and the estimates endpoint returns 1 quarter + 2 surprises for free.

Access: PRO subscription required for full data. Free and unauthenticated users receive a preview wrapped in {isPreview: true, data: ...}.

---

GET /{ticker}/consensus

Returns the aggregate Wall Street consensus for a ticker: price target band, number of covering analysts, upside-to-current, and buy/hold/sell recommendation counts.

Authentication: PRO required. Free users receive the price target band in full but no recommendation distribution.

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol (e.g. AAPL)

Example Request:

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

from sentisense import SentiSenseClient

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
result = client.get_analyst_consensus("AAPL")
band = result["data"]
print(f"Target low/mean/high: {band['targetLow']} / {band['targetMean']} / {band['targetHigh']}")
print(f"{band['numberOfAnalysts']} analysts, consensus: {band['consensusLabel']}")

Response Schema:

Field	Type	Description
isPreview	boolean	true when the caller is on the FREE tier
previewReason	string	"PRO_REQUIRED" or null
data	object	Consensus object (see below)

Consensus object:

Field	Type	Description
ticker	string	Stock ticker
currentPrice	decimal	Reference current price used for upside calculation
targetLow	decimal	Lowest analyst price target
targetMean	decimal	Mean analyst price target
targetHigh	decimal	Highest analyst price target
targetMedian	decimal	Median analyst price target
numberOfAnalysts	int	Number of analysts contributing to the band
upsidePercent	decimal	Implied upside from current price to mean target (%)
consensusLabel	string	Plain-text consensus (e.g. "Strong Buy", "Buy", "Hold", "Sell")
recommendationMean	decimal	Numeric consensus score (PRO only; nullable in preview)
strongBuy	int	Number of Strong Buy ratings (PRO only; 0 in preview)
buy	int	Number of Buy ratings (PRO only; 0 in preview)
hold	int	Number of Hold ratings (PRO only; 0 in preview)
sell	int	Number of Sell ratings (PRO only; 0 in preview)
strongSell	int	Number of Strong Sell ratings (PRO only; 0 in preview)
updatedAt	string	ISO timestamp of the last refresh

Returns 404 if no analyst coverage data is available for the ticker.

---

GET /{ticker}/actions

Returns recent analyst upgrade and downgrade actions for a ticker, newest first.

Authentication: PRO required. Free users receive the 3 most recent actions in full.

Parameters:

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

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/analyst/AAPL/actions?lookbackDays=30"

Action object:

Field	Type	Description
ticker	string	Stock ticker
actionDate	string	Date of the action (ISO date)
firm	string	Brokerage/research firm name
actionType	string	UPGRADE, DOWNGRADE, INITIATE, REITERATE, or OTHER
fromGrade	string	Previous rating (e.g. "Hold"), nullable on initiations
toGrade	string	New rating (e.g. "Buy"), nullable on coverage drops

---

GET /{ticker}/estimates

Returns forward EPS estimates and recent earnings surprise history for a ticker.

Authentication: PRO required. Free users receive 1 estimate (current quarter) + 2 most recent surprises.

Parameters:

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

Response shape:

Field	Type	Description
data.estimates	array	Forward EPS estimate periods (PRO: full history; FREE: 1 row)
data.surprises	array	Earnings surprise history (PRO: full history; FREE: 2 rows)

The estimates array elements describe a fiscal period with low/mean/high EPS estimates and the number of contributing analysts. The surprises array elements describe a past report with actual EPS, estimate, and surprise percent. Refer to the SDK type definitions for full field lists.

---

GET /activity

Returns market-wide recent analyst actions across all covered tickers, newest first.

Authentication: PRO required. Free users receive the 5 most recent actions.

Parameters:

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

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/analyst/activity?lookbackDays=7"

Response shape matches the per-ticker /actions endpoint, with each entry's ticker field identifying the stock.

---

Errors

Status	Code	Description
400	invalid_parameter	lookbackDays outside the 1 to 365 range
401	api_key_required	No API key on a programmatic call
403	quota_exceeded	Monthly request quota for your tier is used up
404	not_found	Ticker has no analyst coverage data