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: ...}.

Building an AI agent? See How to track analyst ratings and price targets with an API for the consensus-plus-sentiment divergence pattern, with a runnable snippet.

---

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	Consensus label in enum form, 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, paged. Ordered by action date descending, with ties broken by ticker ascending so paging is stable.

Authentication: API key required; the first page is full data on every tier. Free keys receive the first 50 rows of the window as a complete response (isPreview: false); requesting limit above 50 or an offset past row 50 returns the free in-allowance slice with previewReason: "PRO_REQUIRED". PRO keys page the whole window.

Parameters:

Parameter	Type	Required	Default	Description
lookbackDays	int	No	30	Days of history to search
limit	int	No	50	Page size, capped at 500. Returns 400 invalid_limit below 1
offset	int	No	0	Rows to skip. Returns 400 invalid_offset when negative
actionTypes	string	No	-	CSV filter on action type: any of UPGRADE, DOWNGRADE, INITIATE, REITERATE, OTHER (case-insensitive). Unknown values return 400 invalid_actionTypes

Response: { isPreview, previewReason, totalCount, data: [...] }. totalCount is the number of actions in the whole lookbackDays window after the actionTypes filter, not the size of the page, so offset + data.length < totalCount tells you another page is available.

Roughly 83% of all analyst actions are REITERATE: an analyst confirming a rating they did not change. If you want actual rating changes (the usual question), filter for them:

# real rating changes only: upgrades, downgrades, and coverage initiations
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/analyst/activity?actionTypes=UPGRADE,DOWNGRADE,INITIATE"

Around 200 rating actions land on a single active market day. Because rows come back newest first, the default 50-row page is typically filled by the newest day alone, and raising lookbackDays on its own returns no additional history. Raise limit for a wider slice, or walk the window with offset:

# every action in the last 30 days, 500 at a time
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/analyst/activity?lookbackDays=30&limit=500&offset=0"
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/analyst/activity?lookbackDays=30&limit=500&offset=500"

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
400	invalid_limit	limit below 1 on /activity (values above 500 are capped, not rejected)
400	invalid_offset	offset below 0 on /activity
400	invalid_actionTypes	actionTypes on /activity contains a value outside UPGRADE, DOWNGRADE, INITIATE, REITERATE, OTHER
401	api_key_required	No API key on a programmatic call
429	quota_exceeded	Monthly request quota for your tier is used up
404	not_found	Ticker has no analyst coverage data