Wealthnow
Sign up

API ReferenceMacro, Rates & FX

Status

Earnings history

GET/api/v3/intel/earnings_history/{ticker}
Plan
Starter and up
Price
2 credits per call
MCP tool
intel_earnings_history

Last N quarters of earnings for a ticker — report date, EPS estimate vs actual, surprise %, and the earnings-reaction price move %. Used by the verdict prompt to anchor 'stock typically moves ±X% on earnings' claims in real numbers. EPS is company-adjusted (eps_basis 'adjusted', the basis the consensus estimate is struck on). report_date is the announcement date (it used to be the calendar-quarter end; null when unknown); calendar_quarter_end is the estimates feed's period label and fiscal_quarter_end identifies the quarter. day_move_pct is the open-to-close move of the session that traded on the release: the NEXT session for an after-close report (it used to be the report date's own session, before the news). day_move_date names that session; day_move_basis is reaction_session | release_time_unknown (first session on or after report_date) | reaction_session_pending (not closed yet; the move is null). reaction_move_pct is the last close before the release to the reaction close (null unless the release time is known), summarized by avg/max_abs_reaction_move_pct beside avg/max_abs_day_move_pct. warning report_dates_unavailable = the date source failed. eps_estimate is the estimates feed's current consensus for the quarter, undated (eps_estimate_as_of null), not a pre-report snapshot; street_mean_eps is the options-flow feed's for the same quarter. surprise_outcome is beat|miss|in_line when the actual is on the same side of both, 'uncertain' when they straddle it (surprise_outcome_reason); beat_rate_pct counts beats among quarters_scored and leaves quarters_uncertain out. quarters_returned can be fewer than lookback_quarters (lookback_note): the feed answers only its most recent quarters, 4 today. Composite (estimates feed + options-flow report dates + daily bars). 6h cache.

Parameters

Path

tickerstringRequired

Query

lookback_quartersintegerOptional

Number of past earnings events to return. The estimates feed answers only its most recent 4 quarters today; quarters_returned says how many came back.

Default4
Range1 to 12

Response

A 200 is a JSON envelope: ok: true and this endpoint's own fields (see Macro, Rates & FX). It carries X-Request-ID, the credit headers (X-Credits-Cost, X-Credits-Remaining, X-Credits-Receipt, X-Credits-Settlement) and the rate-limit headers.

A 200 is billed even when it holds no data (an empty list, null, found: false), so check those fields. Pricing & credits explains the credit headers.

Errors

No error is billed. The body is { "ok": false, "error", "detail", "request_id" }; read the code from error.

ErrorMeaning
400 invalid_tickerThe request is malformed, for example a ticker that is not a symbol: invalid_ticker, refused before any credit is reserved, with param naming the parameter. Not billed.
401 unauthorizedMissing or invalid API key.
402 plan_requiredYour plan does not include this tool, you are out of credits, or your workspace's spend cap paused its keys. plan_required names the plan that unlocks the tool; usage_exceeded means the credit balance is spent; spend_cap_reached means the key is paused until the cap resets or is raised: detail names the cap and the reset, cap_usd and resets_at (ISO 8601) carry them, and doc_url links pricing and credits. Not billed.
403 scope_deniedThis API key is limited to some products and this tool is not one of them. product names the tool's product and scopes the key's products. An upgrade does not change it: use a key whose scopes include the product, or change this key's scopes. Not billed.
404 unknown_tickerNo data source lists this ticker, active or delisted: the market-data listing and the security master both say it does not exist. param names the parameter. Not billed. Best-effort: it is answered only when the route itself found nothing, and after 20 lookups of new symbols per API key per minute the route's own answer stands.
422 validationA parameter is missing, out of range or the wrong type; param names it. Not billed.
429 rate_limitedYour plan's rate limit is spent for this window. Retry after Retry-After seconds. Not billed.
503 paid_data_unavailableThe data could not be served completely right now; retry later. Not billed.
504 request_timeoutThe request ran past the server's time budget; retry. Not billed.

This table lists what the spec declares for this route. Error responses lists every code FIRM sends, with when to retry.

Guides

Read the Macro, Rates & FX guide for this endpoint's fields and examples.