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 follow the watch-list rule: your own list, or every upcoming preview 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 up to 500 rows at a time; use offset to page through the rest. 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?format=json&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, 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.

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 /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 row carries these:

With detail=expanded (Investor and Trader)

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?

Works with Claude Desktop, Claude Code, Cursor and anything else that supports MCP. You need Node.js 18 or newer.

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

Restart the app afterwards. Four tools appear:

Limits and fair use

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