# Economic Calendar & Fed Watch - FOMC, CPI, NFP, Macro Events (`michael_b/economic-calendar-fed-watch`) Actor

Forward-looking macro economic events with consensus, prior, and surprise: CPI, NFP, GDP, FOMC decisions, Fed speeches, central bank meetings. Sources: Finviz (US), Federal Reserve (FOMC + speeches), Investing.com (international + past actuals). Built for AI agents and MCP pipelines.

- **URL**: https://apify.com/michael\_b/economic-calendar-fed-watch.md
- **Developed by:** [Michal Búci](https://apify.com/michael_b) (community)
- **Categories:** AI, Agents, News
- **Stats:** 4 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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:

```json
{
  "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)

```bash
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:

```json
{}
```

**FOMC + Fed speeches scan** — next 30 days:

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

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

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

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

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

**Targeted lookup** — when is the next CPI?

```json
{
  "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.

# Actor input Schema

## `daysAhead` (type: `integer`):

How many days into the future to include. 14 = next two weeks, enough to catch the next CPI/NFP/FOMC even late in a quiet week. Set 7 for just the upcoming trading week.

## `daysBack` (type: `integer`):

How many days of past events to include. 0 = upcoming-only (default; past data is FRED's job). Set higher for surprise post-mortems and trend analysis.

## `country` (type: `array`):

ISO 3166-1 alpha-2 country codes. \['US'] is the default. International coverage via Investing.com requires includeInvesting=true.

## `importance` (type: `string`):

Each source assigns importance differently (Finviz curates 1-3, Investing.com curates with bull icons, Fed events default to 'high' for FOMC/minutes/statements/Beige Book and 'medium' for everything else). The three roughly agree on the big releases. What to expect:

• 'High only' — only the headline-mover releases: NFP, CPI, FOMC decisions, ISM PMI, GDP, jobless claims, Michigan sentiment. Typical week: 5-15 rows. Best for AI agent context budgets.

• 'Medium and above' — adds tier-2 releases: ADP, retail sales, durable goods, building permits, factory orders, Fed speeches, manufacturing PMIs. Typical week: 30-60 rows.

• 'All importance levels' — adds Treasury auctions, EIA oil/gas inventory, mortgage indices, regional Fed surveys, statistical publications. Typical week: 100-200+ rows.

If unsure or you need the full picture, pick 'All importance levels' and filter downstream — sources are noisy in different ways.

## `eventTypes` (type: `array`):

Which event categories to include. Speeches and auctions are excluded by default to reduce noise.

## `keyword` (type: `string`):

Free-text match on event name. Useful for targeted lookups: 'CPI', 'FOMC', 'Powell', 'jobless'. Case-insensitive substring match.

## `includeFinviz` (type: `boolean`):

Scrape Finviz economic calendar. Best US coverage for the current week with TradingEconomics consensus baked in. Default: true.

## `includeFed` (type: `boolean`):

Scrape federalreserve.gov calendar.json for FOMC meetings, press conferences, minutes release dates, Beige Book, member speeches, and testimony. Unique to this actor.

## `includeInvesting` (type: `boolean`):

Scrape investing.com economic calendar. Adds international coverage and the forward calendar beyond the current week (Finviz only carries the current week, so without this the next CPI/NFP won't show until that week arrives). Required for non-US countries and Last-N surprises analysis. Default: true.

## `limit` (type: `integer`):

Hard cap on total events. 0 = unlimited (default — return everything that matches the filters). Set to a positive integer (e.g. 50) to limit context for AI agents. The 10000 maximum is a safety net; even greedy 60-day scans rarely return more than 500 rows.

## Actor input object example

```json
{
  "daysAhead": 14,
  "daysBack": 0,
  "country": [
    "US"
  ],
  "importance": "high",
  "eventTypes": [
    "release",
    "meeting",
    "statement",
    "press_conference",
    "minutes",
    "beige_book"
  ],
  "includeFinviz": true,
  "includeFed": true,
  "includeInvesting": true,
  "limit": 0
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset of macro events with normalized fields: eventName, eventNameStandard, eventType, country, scheduledAt (UTC), importance, consensus, actual, prior, surprise vs consensus / prior / direction, speaker info, source.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("michael_b/economic-calendar-fed-watch").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("michael_b/economic-calendar-fed-watch").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call michael_b/economic-calendar-fed-watch --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=michael_b/economic-calendar-fed-watch",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/1nqJCcHj9cIdt7UN9/builds/Iy9YX2dh4O63S08ZV/openapi.json