Zacks APIzacks.com ↗
Retrieve EPS surprise data for any stock from Zacks.com. Get reported vs estimated EPS, surprise %, and positive surprise ratio for the last 4 quarters.
What is the Zacks API?
The Zacks EPS Surprise API exposes one endpoint — get_eps_surprise_ratio — that returns up to 8 data fields per quarter across the last four reporting periods for any US-listed stock ticker. Each response includes reported EPS, estimated EPS, the difference, the surprise percentage, and a computed positive_surprise_ratio indicating how consistently a company has beaten analyst forecasts.
curl -X GET 'https://api.parse.bot/scraper/efcccfa3-ef67-478b-a6e9-ff92d2c08851/get_eps_surprise_ratio?ticker=AAPL' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace zacks-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Zacks EPS Surprise API — fetch and inspect earnings surprises."""
from parse_apis.zacks_com_api import Zacks, InputFormatInvalid
client = Zacks()
# Fetch EPS surprise data for a well-known ticker.
try:
eps = client.eps_surprises.get(ticker="AAPL")
except InputFormatInvalid as e:
print(f"Invalid ticker format: {e.message}")
raise
# Display the overall positive surprise ratio.
print(f"{eps.ticker}: {eps.positive_surprise_count}/{eps.available_quarter_count} positive surprises")
print(f"Ratio: {eps.positive_surprise_ratio} Status: {eps.ratio_status}")
# Walk individual quarters (newest to oldest).
for q in eps.quarters:
print(
f" {q.quarter_label} ({q.quarter_position}): "
f"reported={q.reported_eps} vs estimated={q.estimated_eps} "
f"diff={q.difference} surprise={q.eps_surprise_percent}%"
)
print("exercised: eps_surprises.get / Quarter fields / ratio fields")
Fetches the EPS Surprise (last 4 quarters) section from a stock's Zacks quote overview page. Returns four quarters in newest-to-oldest order with reported EPS, estimated EPS, difference, and EPS surprise percentage. Computes positive_surprise_ratio as the count of quarters with strictly positive surprise percentage divided by 4. If any quarter's EPS Surprise % is N/A or missing, positive_surprise_ratio is null and ratio_status is 'no_info'. One upstream page request per call.
| Param | Type | Description |
|---|---|---|
| tickerrequired | string | Stock ticker symbol (1-5 uppercase letters, optionally followed by a dot or hyphen and 1-2 letters for share classes like BRK.B). Example: AAPL, MSFT, BRK.B. |
{
"type": "object",
"fields": {
"ticker": "string — the stock ticker symbol",
"quarters": "array of 4 quarter objects in newest-to-oldest order, each with quarter_position, quarter_label, reported_eps, estimated_eps, difference, eps_surprise_percent, and status",
"ratio_status": "string — 'calculated' when all 4 quarters are available, 'no_info' otherwise",
"source_status": "string — 'success' when data was extracted successfully",
"available_quarter_count": "integer — number of quarters with available (non-N/A) data",
"positive_surprise_count": "integer — number of quarters with EPS surprise % strictly greater than zero",
"positive_surprise_ratio": "number or null — positive_surprise_count divided by 4, or null if any quarter is unavailable"
},
"sample": {
"data": {
"ticker": "AAPL",
"quarters": [
{
"status": "available",
"difference": 0.03,
"reported_eps": 1.91,
"estimated_eps": 1.88,
"quarter_label": "6/26",
"quarter_position": "Q0",
"eps_surprise_percent": 1.6
},
{
"status": "available",
"difference": 0.09,
"reported_eps": 2.01,
"estimated_eps": 1.92,
"quarter_label": "3/26",
"quarter_position": "Q-1",
"eps_surprise_percent": 4.69
},
{
"status": "available",
"difference": 0.19,
"reported_eps": 2.84,
"estimated_eps": 2.65,
"quarter_label": "12/25",
"quarter_position": "Q-2",
"eps_surprise_percent": 7.17
},
{
"status": "available",
"difference": 0.12,
"reported_eps": 1.85,
"estimated_eps": 1.73,
"quarter_label": "9/25",
"quarter_position": "Q-3",
"eps_surprise_percent": 6.94
}
],
"ratio_status": "calculated",
"source_status": "success",
"available_quarter_count": 4,
"positive_surprise_count": 4,
"positive_surprise_ratio": 1
},
"status": "success"
}
}About the Zacks API
What the API Returns
The get_eps_surprise_ratio endpoint accepts a single required parameter, ticker (1–5 uppercase letters, with optional dot or hyphen suffix for share classes), and returns the EPS Surprise section from that stock's Zacks quote overview page. The quarters array contains four objects ordered newest-to-oldest, each carrying quarter_label, reported_eps, estimated_eps, diff, and the EPS surprise percentage for that period.
Computed Fields and Status Signals
Beyond the raw quarterly data, the response includes three summary fields. positive_surprise_count is the number of quarters where the EPS surprise percentage was strictly greater than zero. positive_surprise_ratio divides that count by 4 — giving a value between 0 and 1 — but returns null if any quarter has unavailable data. ratio_status is set to 'calculated' when all four quarters are present and 'no_info' otherwise. available_quarter_count tells you exactly how many quarters returned non-N/A values.
Coverage and Ticker Format
The endpoint works with standard US equity tickers. For stocks with share classes, append a dot or hyphen followed by the class letter (e.g., BRK.B or BRK-B). The data reflects the four most recently reported fiscal quarters as shown on Zacks, so coverage depends on whether the company has at least one reported quarter on record. If Zacks has no data for a ticker, ratio_status will be 'no_info' and positive_surprise_ratio will be null.
The Zacks API is a managed, monitored endpoint for zacks.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when zacks.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official zacks.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Screen stocks by
positive_surprise_ratioto find companies that consistently beat consensus EPS estimates - Track whether a specific stock's earnings beat or miss streak is improving or deteriorating across the last four quarters
- Feed
diffand surprise percentage values into a quant model that weights earnings momentum - Alert when a newly reported quarter changes a stock's
positive_surprise_ratiofrom below 0.5 to above 0.5 - Compare
reported_epsvsestimated_epsacross peers in the same sector to gauge relative forecast accuracy - Populate an earnings quality dashboard that displays the
quarter_labeland surprise percentage for each of the last four periods
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Zacks have an official developer API?+
What does `positive_surprise_ratio` actually measure, and when is it null?+
positive_surprise_ratio is positive_surprise_count divided by 4, where positive_surprise_count counts quarters with an EPS surprise percentage strictly greater than zero. It is null whenever any of the four quarters has unavailable data (N/A), which also sets ratio_status to 'no_info' and reduces available_quarter_count below 4.Does the API return EPS surprise data for more than four quarters?+
Does the API cover non-US or OTC-listed stocks?+
ratio_status: 'no_info' and a null positive_surprise_ratio. You can fork this API on Parse and revise it to target a different data source with broader international coverage.