EarningsPulse

Earnings calendar, EPS actuals & surprises, and forward-guidance signals read straight out of SEC EDGAR 8-K press releases.

EarningsPulse turns the quarterly-earnings firehose into clean JSON. Pull the earnings calendar for any date range, see who reported beats and misses, and get a forward-guidance read extracted directly from each company's 8-K filing — including the exact sentences (with dollar figures intact) where management talks about the next quarter. Built on free, authoritative public sources: the Nasdaq earnings calendar and SEC EDGAR.

Endpoints

Endpoint	What it returns
`GET /health`	Service liveness check — `status`, `service`, `timestamp`.
`GET /earnings/calendar?from=YYYY-MM-DD&to=YYYY-MM-DD`	All earnings events across a date range. Each row: `ticker`, `company`, `report_date`, `time`, `market_cap`, `fiscal_quarter`, `eps_actual`, `eps_estimate`, `eps_surprise_pct`, `beat_miss`, `analyst_count`, `last_year_eps`. Already-reported companies carry `eps_actual` and `eps_surprise_pct`; scheduled (future) rows list the reporter without actuals.
`GET /earnings/guidance/:ticker/:quarter`	Forward-guidance signal mined from the company's most relevant 8-K. Returns `ticker`, `quarter`, `report_date`, `guidance_tag`, `next_quarter_eps_guidance_low`/`_high`, `next_quarter_revenue_guidance_low_bn`/`_high_bn`, `raw_snippets` (readable guidance sentences pulled from the EX-99.1 press-release exhibit), `filing_date`, `cik`. Quarter format: `Q1_FY2026`.
`GET /earnings/movers/postmarket`	Today's earnings reporters from the Nasdaq calendar. Each row: `ticker`, `company`, `report_date`, `time`, `eps_estimate`, `last_year_eps`, `market_cap`.

Every response is wrapped with a source field (live or cache) so you always know if you hit fresh data or a cached copy.

Why this API

Real guidance language, not just a number. The /guidance endpoint goes past the 8-K cover page to the EX-99.1 press-release and CFO-commentary exhibits — where guidance actually lives — and returns the verbatim sentences in raw_snippets with dollar amounts kept whole (e.g. "$45.6 billion"). You get the source text, not a black box.
A direction tag on every filing. Each guidance lookup is classified into a guidance_tag: RAISED, LOWERED, IN-LINE, PROVIDED (given but direction unclear), NOT_PROVIDED, or UNAVAILABLE — so you can screen for guidance moves at a glance.
Authoritative public sources, no scraping fragility. Calendar and actuals come from the Nasdaq earnings API; guidance comes from SEC EDGAR's official ticker→CIK mapping and filing APIs. No paywalled data resold.
Calendar with built-in beat/miss. Where both an actual and estimate are present, rows are tagged BEAT/MISS/IN-LINE for you.
Cached and fast. Results are Redis-cached (calendar/guidance hourly, post-market movers ~5 min) and tagged source: live|cache.

Typical use cases

Build an earnings dashboard or calendar widget — pull a week of reporters and highlight today's movers.
Screen for companies that raised or lowered forward guidance right after they report, using guidance_tag.
Surface the exact guidance sentences from a company's earnings release without parsing SEC HTML yourself.
Track beat/miss reactions: combine /calendar actuals with eps_surprise_pct to flag big surprises.
Feed earnings events and guidance snippets into an alerting bot, newsletter, or LLM pipeline.

Good to know

Guidance number fields are best-effort. next_quarter_eps_guidance_low/high and next_quarter_revenue_guidance_low_bn/high_bn are parsed from filing text and may be null — guidance formats vary, and the API deliberately does not emit a number it can't reliably attribute to the quarter. The guidance_tag plus raw_snippets are the primary deliverable; treat the structured numbers as a bonus.
eps_estimate is null on the standard deployment. The free Nasdaq calendar provides reported actuals and surprise %, not forward analyst estimates, so eps_estimate stays null throughout the calendar. (Consensus estimates would require an FMP estimates-provider key, which is not provisioned.)
Per-row sparsity is normal. Individual calendar rows may omit analyst_count, last_year_eps, or market_cap depending on Nasdaq coverage for that name.
Freshness. Calendar and guidance are cached ~1 hour; post-market movers ~5 minutes. EDGAR guidance looks at 8-K filings within roughly a week of the report date.
Quarter format is strict. :quarter must match Q1_FY2026; anything else returns 400 with an example. Tickers are case-insensitive.
If EDGAR can't be reached for a request, guidance_tag comes back as UNAVAILABLE (or NOT_PROVIDED when no qualifying 8-K is found) with an empty raw_snippets array rather than failing the call.