Data API

What you can access

Every endpoint covers your watch list, and that is what a request returns unless you say otherwise. A Trader subscription can also reach the whole universe — every company with analyst coverage, around 4,500 names — by adding scope=universe. It is a choice per request, not a setting: ask for scope=watchlist any time you only want your own stocks.

Written previews and earnings history follow the watch-list rule: your own list, or every company with a Trader subscription. The confirmed calendar is wider on purpose — a schedule of who reports when isn’t analysis, so Investors get the whole population too.

Requests return 100 rows unless you ask for more with limit, up to 500 at a time. When meta.has_more is true, raise offset by your limit and ask again; when it’s false, you have everything. The per-company limits above are a ceiling on how much one subscription can pull, not a limit on how many stocks you can follow.

Your keys

A key identifies you and carries your subscription. Anyone holding it can read your data, so treat it like a password — and if one ever gets out, revoke it here.

Quick start

In a browser or with curl

curl -H "X-EW-Key: YOUR_KEY" \
  "https://www.earningswhispers.com/api/v1/earnings?limit=10"

In Excel or Google Sheets

Excel: Data → Get Data → From Web, and paste this URL. It refreshes on whatever schedule you set.

https://www.earningswhispers.com/api/v1/earnings?key=YOUR_KEY

The key parameter exists for tools that can’t send headers. When you can send one, prefer X-EW-Key — a key in a URL ends up in browser history and server logs along the way.

In Python

import requests

r = requests.get(
    "https://www.earningswhispers.com/api/v1/earnings",
    headers={"X-EW-Key": "YOUR_KEY"},
    params={"scope": "universe", "grade_min": 10, "confirmed": True, "limit": 50},
)
for row in r.json()["data"]:
    print(row["ticker"], row["epsDate"], row["whisper"], row["grade"])

Endpoints

Base URL https://www.earningswhispers.com/api/v1. Everything returns JSON. Authenticate with an X-EW-Key header or a key query parameter.

GET /me

What your key can do — tier, scopes, detail levels, how far history reaches (history: any, watchlist or none) — and how many requests you have left today. The first thing to check when something is refused.

GET /earnings

Upcoming earnings, filtered. Narrow it — a date range or a handful of tickers uses one request where an unfiltered pull uses many.

Every list comes back as { "meta": { ... }, "data": [ ... ] }. meta repeats the scope, detail, limit and offset you asked for, with count rows returned and has_more saying whether another page is waiting.

GET /calendar

The confirmed earnings calendar: who reports on which day, the time of day, market cap, and the implied and average moves. Lighter than /earnings, and available across every confirmed date for Investors as well as Traders. Defaults to every confirmed date from today out to 120 days.

Returns ticker, company, epsDate, epsTime, period, confirmed, marketCap, url, impliedMove, avgMove and avgVolume. The same data backs the download button on the monthly calendar.

GET /company/{ticker}

One company’s next report. Takes detail.

GET /history/{ticker}

The last 20 reports — about five years — for one company, newest first: how it did against the whisper and consensus, revenue against its estimate, guidance, and how the stock traded around each report. Traders can ask for any company; Investors for companies on their watch list.

Each entry in prices has a day: 0 is tradingDate, -1 the session before it, 1 the session after. Days count trading sessions, not calendar days, so weekends and holidays never leave gaps. A report from the last two weeks has fewer than 10 sessions after it until they trade.

{ "date": "2026-08-04", "releaseTime": "AMC", "tradingDate": "2026-08-05",
  "eps": 1.66, "whisper": 1.69, "consEst": 1.62, "guidance": "Positive",
  "prices": [
    { "day": -1, "date": "2026-08-04", "open": 504.00, "close": 518.58, ... },
    { "day":  0, "date": "2026-08-05", "open": 484.49, "close": 482.05, ... },
    ... ] }

GET /previews

The written previews: headline, opening paragraph and a link to the full piece. Takes scope — watchlist by default, or universe for every upcoming preview (Trader) — plus limit and offset.

When something goes wrong

Every error carries a plain-English error.message explaining what happened.

Fields

Every /earnings and /company row carries these:

With detail=expanded (Investor and Trader)

These appear only on an expanded request. A standard response leaves them out rather than sending them empty.

EPS and consensus are both reported on the option-expense-adjusted basis, so they compare directly. The Whisper is already quoted that way.

Use with AI

The MCP server connects your data to an AI assistant, so you can ask questions instead of writing requests:

What’s reporting on my watch list this week, and which have a grade of A− or better?

How often has AMD beaten the whisper over the last five years, and how did the stock trade the week after?

Works with Claude Desktop, Claude Code, Cursor, VS Code and anything else that supports MCP. You need Node.js 20 or newer, and a key from above — the server won’t start without one.

Claude Desktop

Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "earnings-whispers": {
      "command": "npx",
      "args": ["-y", "earningswhispers-mcp"],
      "env": { "EW_API_KEY": "YOUR_KEY" }
    }
  }
}

Claude Code

claude mcp add earnings-whispers \
  --env EW_API_KEY=YOUR_KEY \
  -- npx -y earningswhispers-mcp

Cursor and VS Code

Cursor: add the Claude Desktop block above to ~/.cursor/mcp.json. VS Code: add it to .vscode/mcp.json, with "servers" in place of "mcpServers".

On Windows, if the assistant can’t start npx, use "command": "cmd" and "args": ["/c", "npx", "-y", "earningswhispers-mcp"].

Restart the app afterwards. Six tools appear:

Limits and fair use

• Requests are counted per key per day and reset at midnight. /me reports what’s left.
• 100 rows a page by default, up to 500 with limit; use offset for the rest.
• The data is for your own use. Redistributing it, or republishing it as your own feed, needs a license — get in touch.
• Keys are yours alone. If you need access for a team, talk to us about an institutional license rather than sharing one.