Economic Calendar & Fed Watch

Forward-looking macro economic events for AI agents — CPI, NFP, GDP, FOMC decisions, Fed speeches, central bank meetings — with consensus, prior, and a precomputed surprise verdict. Designed primarily as an MCP tool for AI agents doing portfolio analysis, pre-trade risk checks, and macro briefings.

---

Quick example

A row for the May 2026 Non Farm Payrolls release looks like:

{
  "scheduledAt": "2026-05-08T12:30:00Z",
  "country": "US",
  "importance": "high",
  "eventName": "Non Farm Payrolls",
  "eventType": "release",
  "consensus": 60.0,
  "actual": null,
  "prior": 178.0,
  "unit": "thousands",
  "surpriseDirection": null,
  "surpriseVsConsensus": null,
  "surpriseVsPrior": null,
  "...": "..."
}

When the release prints, actual fills in and surprise fields auto-populate.

---

Output fields

Fields are ordered most-useful-first. Sparse fields (only populated for specific event types) are noted.

Primary (always populated)

Field	What it means
scheduledAt	When the event releases / starts. ISO 8601 UTC, always ends in Z.
country	ISO 3166-1 alpha-2 country code. v1 is mostly US; international with Investing.com enabled.
importance	Normalized impact: low, medium, high. Filter to high to cut macro noise. See How importance is set below for source-specific details.
eventName	Source-published name. e.g. Non Farm Payrolls, Fed Williams Speech, FOMC Minutes.
eventType	release / meeting / statement / press_conference / minutes / speech / testimony / auction / beige_book / other.

Headline values (the "what happened / what's expected")

Field	What it means
consensus	What economists/analysts think the actual will be, parsed numeric. The market's expectation. Null when no consensus is published or the event isn't numeric (speeches, meeting dates).
actual	The released value, parsed numeric. Null for upcoming events that haven't released yet.
prior	Same indicator from the previous reporting period (last month / last quarter). Helps gauge trend.
unit	Unit of those numeric values: percent, thousands, millions, billions, index, count, currency_usd. Without this an LLM can't tell whether 60 is "lots" or "barely anything".
surpriseDirection	Quick verdict: beat = bullish vs expectation; miss = bearish; inline = within tolerance. Accounts for inverse indicators (higher unemployment = miss, not beat). Null when actual or consensus is missing.
surpriseVsConsensus	actual − consensus, same unit. The standard surprise metric used to price-in macro risk.
surpriseVsPrior	actual − prior, same unit. Useful for trend/narrative ("is the indicator turning?").

How to read consensus / actual / prior in plain English:

• Consensus = "what the market expects to happen"
• Actual = "what actually got released"
• Prior = "what the same indicator was last time"
• Surprise = actual − consensus. Positive surprise ≠ always good — it depends on the indicator. surpriseDirection gives you the macro-meaningful answer.

Secondary numeric / standardization

Field	What it means
forecast	Alternate forecast where the source publishes one (e.g. TradingEconomics on Finviz). Often null. When present and different from consensus, it's a second opinion.
eventNameStandard	Controlled-vocabulary identifier for cross-source matching: NFP, CPI_YOY, FOMC_DECISION, FED_SPEECH, etc. Use this to filter or join across data sources. Unmapped events use UNKNOWN_ prefix.
importanceScore	Importance as integer 1 (low) / 2 (medium) / 3 (high). For sortability.
isHigherPositive	Direction encoding: 1 = higher actual is bullish for the subject (GDP, jobs); -1 = bearish (unemployment, inflation, jobless claims); 0 = neutral. Drives surpriseDirection.
period	Human-readable period the data covers: April 2026, Q1 2026.
referencePeriodEnd	ISO date when the reporting period ends. Useful for joining to date-indexed data.
currency	ISO 4217 currency code associated with the country.

Speech-specific (only populated for speech / testimony rows)

Field	What it means
speakerName	Speaker's name, e.g. Christopher J. Waller.
speakerRole	Speaker's title: Chair, Vice Chair for Supervision, Governor, FOMC Member.
speechTopic	Subject the speaker is addressing, when published.
speechVenue	Physical / online venue.
transcriptUrl	URL to the prepared remarks / transcript (when published). Inline text is intentionally NOT included — saves tokens.
livestreamUrl	URL to a livestream when scheduled (FOMC press conferences, some Fed speeches).

Provenance / debug (always present, useful for audits)

Field	What it means
rawConsensus / rawActual / rawPrior	Source-formatted strings before parsing — e.g. "60K", "$7.5B", "2.4%". Useful for fidelity / debugging if a parse looks wrong.
sourceName	Finviz / FederalReserve / Investing.
sourceUrl	Canonical URL of the calendar landing page (not per-event).
eventUrl	Best available per-event detail page URL. Investing.com 100%, Finviz ~97%, Fed ~3-10%. When two sources both cover the same event, the URL with the richer detail page wins (so a Fed-source row can carry an Investing URL through dedup).
sourceEventId	The source's own internal event identifier (Finviz calendarId, Investing event_attr_id). Useful if you want to merge this with separate scrapes from the same source. Null for federalreserve.gov calendar.json (no stable ID).
eventId	Stable cross-source dedup key: country-YYYY-MM-DD-eventNameStandard. Survives reruns and source merging.
scrapedAt	ISO 8601 UTC timestamp this row was scraped. Lets you reason about data freshness.

---

MCP usage (Claude Code, Cursor, any MCP-compatible LLM)

$npx @apify/actors-mcp-server --tools michael_b/economic-calendar-fed-watch

The actor exposes its input schema as an MCP tool. Example agent prompts:

• "What high-impact macro events are coming this week that could move SPY?"
• "When is the next FOMC meeting?"
• "Show me Fed speeches scheduled for the next 7 days."
• "Did last week's CPI print beat or miss consensus?"

---

Sources

Source	Coverage	Anti-bot
Finviz /calendar/economic	US, current trading week, with TradingEconomics consensus	None
Federal Reserve calendar.json + ne-speeches.json	FOMC meetings, press conferences, minutes, Beige Book, Fed speeches/testimony	None
Investing.com getCalendarFilteredData AJAX	International + historical actuals (50+ countries)	curl_cffi Chrome impersonation

Default behavior

With defaults (daysAhead=7, country=US, importance=high, includeFinviz=true, includeFed=true, includeInvesting=false) the actor returns the next 7 days of high-impact US events plus FOMC dates and statement releases — typically 5–15 rows, well under any agent's context budget.

Common configurations

Pre-trade risk scan (default) — high-impact US events for the next week:

{}

FOMC + Fed speeches scan — next 30 days:

{
  "daysAhead": 30,
  "eventTypes": ["meeting", "press_conference", "minutes", "speech", "statement"],
  "importance": "all"
}

Recent surprise post-mortem — last week's high-impact prints with actuals:

{
  "daysAhead": 0,
  "daysBack": 7,
  "importance": "high",
  "includeInvesting": true
}

International macro week — US + EU + UK high-impact:

{
  "country": ["US", "EU", "GB"],
  "daysAhead": 7,
  "importance": "high",
  "includeInvesting": true
}

Targeted lookup — when is the next CPI?

{
  "keyword": "CPI",
  "daysAhead": 45,
  "importance": "all",
  "limit": 1
}

---

How importance is set

The three sources don't share an importance scheme — we normalize each into the same low/medium/high scale:

Source	Where importance comes from
Finviz	Numeric 1/2/3 curated in their JSON. NFP, CPI, FOMC events are 3; ISM/jobless are 2-3; EIA, auctions, lower-tier indicators are 1.
Federal Reserve	We assign it ourselves — calendar.json doesn't carry an importance field. high for FOMC meetings/minutes/statements, press conferences, Beige Book. medium for everything else (speeches, testimony, conferences, statistical releases).
Investing.com	Count of bull icons (1/2/3) curated by Investing. Heavily overlaps Finviz on the big releases (NFP, CPI = 3 bulls).

Practical implication: filtering importance=high returns the same NFP/CPI/FOMC universe across all three sources, but it's a heuristic alignment, not enforced. If you need a strict cross-source importance contract, filter on eventNameStandard (e.g. ["NFP", "CPI_YOY", "FOMC_DECISION"]) instead.

Limits and known gaps

• Finviz exposes only the current trading week. For events outside that window, enable includeInvesting=true.
• Speeches are excluded by default — they're high-volume and noisy. Enable via eventTypes: ["speech"].
• CME FedWatch implied probabilities are not yet included — coming in v1.1. v1 ships FOMC meeting / press conference / minutes dates only.
• Hawkish/dovish speech lean is not inferred — leave that to your LLM.

Pricing

This actor uses pay-per-event:

• Per-run base fee: $0.005
• Per event returned: $0.002

A typical default call (~8 high-impact US events, next week) costs ~$0.021.