earnings

name	earnings
description	Look up earnings dates, EPS beat/miss history, analyst consensus estimates, and estimate revisions for US/global stocks.

Earnings Calendar & Surprise Tracking

Use this skill when the user asks about:

• When a company reports earnings ("when does AAPL report?")
• Whether a company beat or missed estimates ("did NVDA beat last quarter?")
• Upcoming earnings this week/month for a watchlist
• Forward EPS or revenue consensus estimates
• Whether analysts have been raising or cutting estimates

---

Command reference

User intent	Command	Key params
Next earnings date	calendar	symbol
Upcoming earnings for a list	upcoming	symbols, days_ahead
Beat/miss history	surprise	symbol, limit
Forward EPS/revenue estimates	consensus	symbol
Estimate revision trend	revisions	symbol

---

Workflow: "When does X report?"

Call earnings_calendar with command="calendar" and the ticker:

earnings_calendar(command="calendar", symbol="AAPL")

Report: next date, EPS estimate range (low/avg/high), revenue estimate range.

---

Workflow: "Did X beat last quarter?" / "Show me NVDA's earnings history"

Call surprise to get the last 8 reported quarters:

earnings_calendar(command="surprise", symbol="NVDA", limit=8)

Format the response as a table: date | EPS est | EPS actual | surprise % | beat/miss. Summarise the beat rate (e.g. "beat in 7 of the last 8 quarters").

---

Workflow: "What are analysts expecting for MSFT this quarter?"

Call consensus for forward estimates:

earnings_calendar(command="consensus", symbol="MSFT")

Report: current quarter EPS avg/low/high, year-over-year growth, revenue estimate, analyst count and recommendation.

---

Workflow: "Have analysts been cutting estimates for META?"

Call revisions to see upgrade/downgrade counts over recent periods:

earnings_calendar(command="revisions", symbol="META")

Interpret the result:

• More up_last_30_days than down_last_30_days → analysts are bullish / raising numbers
• More down_last_30_days → negative revision trend, worth flagging
• Also check eps_trend to show the actual EPS estimate drift (e.g. current vs 90 days ago)

---

Workflow: "What earnings are coming up this week?"

The user must provide a list of symbols (FinClaw cannot scan the whole market). Ask for their watchlist if not given, then call upcoming:

earnings_calendar(command="upcoming", symbols="AAPL,MSFT,NVDA,AMZN,TSLA,META,GOOGL", days_ahead=7)

Group results by date. For each company show: ticker, date, EPS estimate.

---

Notes

• Data source: Yahoo Finance via yfinance. Coverage is best for US/global large caps.
• upcoming is slow for large lists (one API call per ticker). Keep to ≤ 30 symbols.
• surprise only shows reported quarters — future dates are excluded automatically.
• If a ticker returns "error": "No earnings calendar available", it may be a non-US stock, ETF, or the data is simply not in Yahoo Finance for that ticker.