# Options Event-Risk Calendar (`xprm-llc/options-event-risk-calendar`) Actor

CPI, jobs, FOMC, GDP, PCE, auctions, opex & NYSE holidays before each option expiration, from official BLS, BEA, Census, Fed & Treasury data.

- **URL**: https://apify.com/xprm-llc/options-event-risk-calendar.md
- **Developed by:** [Paul Scharr](https://apify.com/xprm-llc) (community)
- **Categories:** Business, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 event rows

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Options Event-Risk Calendar

**Know which scheduled market-moving events land before your option expires.** Enter your expiration dates, or just ask for the next N monthly expirations. You get one row per event per expiration: CPI, jobs report, PPI, GDP, PCE, retail sales, FOMC decisions and minutes, and Treasury auctions, plus monthly and quarterly opex, VIX settlement and NYSE holidays. Each row shows the exact time in ET, an impact tier, **days and trading days before expiration**, and a link to the official source.

- **Official sources only:** U.S. Bureau of Labor Statistics (BLS), Bureau of Economic Analysis (BEA), Census Bureau, Federal Reserve Board and U.S. Treasury (TreasuryDirect, with Fiscal Data as a fallback). It reads the agencies' own published calendar files and pages. There's no third-party calendar scraping and no API key.
- **Computed by rule:** standard monthly expiration (3rd Friday, or the prior trading day when that Friday is a holiday), quarterly "quad witching", VIX settlement Wednesdays, and NYSE holidays and 1:00 PM early closes.
- **Alert mode:** schedule it daily and get only events that are **new or moved**. Moved rows show the old time.
- **Robust:** if one agency is down, the run warns and continues with the rest. Error rows are never written, so you're never charged for a failure.
- **No consensus forecasts and no actual values.** Those are proprietary or released later. This Actor tells you *when*, not *what*.

> **Educational, not advice.** This is a scheduling tool for education and research. It isn't investment, trading or tax advice, and it isn't an offer or recommendation to buy or sell any security or option. Agencies can reschedule releases, and exchanges can close unexpectedly. Always confirm critical dates on the official source linked in each row.

### Quick start

1. Leave every field at its default and click **Start**. You get events for the next 2 monthly expirations at medium impact or higher.
2. Or enter your own expirations, e.g. `["2026-11-20", "2026-12-18"]`, and set **Minimum impact** to `high` for a short list.

#### Example inputs

Next two monthly expirations, high-impact only, labelled SPY:

```json
{ "nextMonthlyExpirations": 2, "minImpact": "high", "ticker": "SPY" }
```

A specific weekly and monthly expiration, inflation + jobs + FOMC only:

```json
{ "expirations": ["2026-11-06", "2026-11-20"], "eventTypes": ["inflation", "employment", "fomc"], "minImpact": "medium" }
```

Plain calendar (no expirations) for a date range, everything:

```json
{ "nextMonthlyExpirations": 0, "fromDate": "2026-11-01", "toDate": "2026-11-30", "minImpact": "low" }
```

Daily alert of new or moved high-impact dates (run on a schedule):

```json
{ "nextMonthlyExpirations": 3, "minImpact": "high", "alertMode": true, "stateStoreName": "my-macro-alerts", "windowMode": "sincePreviousExpiration" }
```

#### Example output row (real run, October 17, 2026)

```json
{
  "event": "Consumer Price Index", "category": "inflation", "impact": "high", "agency": "BLS",
  "datetimeET": "2026-11-10T08:30:00-05:00", "dateET": "2026-11-10", "timeET": "08:30", "allDay": false, "timeConfirmed": true,
  "referencePeriod": null, "notes": null,
  "expiration": "2026-11-20", "daysBeforeExpiration": 10, "tradingDaysBeforeExpiration": 8, "ticker": "SPY",
  "sourceUrl": "https://www.bls.gov/schedule/news_release/bls.ics", "infoUrl": "https://www.bls.gov/schedule/news_release/",
  "fetchedAt": "2026-10-17T13:46:33.047Z", "changed": null, "changeStatus": null, "previousDatetimeET": null,
  "eventId": "BLS|c26d524f-228b-46e9-b00e-fdbec26d68af"
}
```

`RUN_SUMMARY` (in the default key-value store) lists windows, rows matched and written, and each source's status.

### Worked examples (real runs, October 17, 2026)

**1. "What could move SPY before the Nov 20 monthly?"** (`expirations: ["2026-11-20"], minImpact: "high"`). 6 rows:

| When (ET) | Event | Days / trading days before exp |
|---|---|---|
| Wed Oct 28, 2:00 PM | FOMC rate decision & statement (Fed) | 23 / 17 |
| Thu Oct 29, 8:30 AM | GDP advance estimate, Q3 2026 (BEA) | 22 / 16 |
| Thu Oct 29, 8:30 AM | Personal Income and Outlays / PCE, Sep (BEA) | 22 / 16 |
| Fri Nov 6, 8:30 AM | Employment Situation (BLS) | 14 / 10 |
| Tue Nov 10, 8:30 AM | Consumer Price Index (BLS) | 10 / 8 |
| Tue Nov 17, 8:30 AM | Advance retail sales, Oct (Census) | 3 / 3 |

**2. December quad witching window.** With `nextMonthlyExpirations: 2` and the default medium impact, the Dec 18, 2026 window also includes the Dec 8–9 FOMC with projections (2:00 PM ET Dec 9), the Dec 10 CPI, the Thanksgiving closure (Nov 26), the Dec 16 VIX settlement and the Dec 18 quarterly expiration itself (daysBeforeExpiration 0).

**3. Iron condor seller, short weekly.** Set `expirations: ["2026-11-06"]` and `minImpact: "high"`. If the jobs report row shows `daysBeforeExpiration: 0`, the event lands on expiration day.

### How the impact tiers work

Tiers are editorial: they reflect how much index implied volatility usually reacts.

- **High:** CPI, Employment Situation, FOMC decisions, GDP advance estimate, Personal Income & Outlays (PCE), advance retail sales, quarterly (quad witching) expiration.
- **Medium:** PPI, JOLTS, Employment Cost Index, later GDP estimates, housing starts, new home sales, durable goods, trade balance, FOMC minutes, 2-year-and-longer nominal Treasury note and bond auctions, monthly opex, VIX settlement, NYSE full-day holidays.
- **Low:** everything else the agencies publish, including bills, TIPS and FRN auctions, regional data and early closes.

### Window modes and cost control

- `fromStart` (default): each expiration's window starts at the start date. An event before two expirations appears twice, each row with its own days-before count.
- `sincePreviousExpiration`: windows don't overlap, so each event appears once and you get fewer rows.
- `maxResults` caps the rows written in a run. `minImpact`, `eventTypes` and `sources` cut rows too.

### Use with AI agents and MCP

This Actor is built to be called by agents through the [Apify MCP server](https://mcp.apify.com). Add `xprm-llc/options-event-risk-calendar` as a tool.

- **Good prompts:** "List high-impact U.S. macro events before my Dec 18 SPX expiration", "Is CPI before or after my Nov 20 options expire?", "Alert me if any FOMC or CPI date moves."
- **Minimal call:** `{"expirations": ["2026-12-18"], "minImpact": "high"}`. Rows are flat JSON with ISO datetimes that include the ET offset, so they're easy to reason over.
- **Tips for agents:** use `windowMode: "sincePreviousExpiration"` to avoid duplicate events, and read `RUN_SUMMARY.sourcesFailed` before concluding that no event exists.
- **Pairs with** [Options Strategy Calculator](https://apify.com/xprm-llc/options-strategy-calculator): check event risk first, then size the trade.

### Data sources and terms

| Source | What | Access |
|---|---|---|
| BLS | Economic news release schedule (iCalendar) | Public domain U.S. government work. Requests identify the Actor in the User-Agent, as BLS asks |
| BEA | Release schedule (iCalendar) | Public domain U.S. government work |
| Census | Economic indicator calendar (yearly list page) | Public domain U.S. government work |
| Federal Reserve Board | FOMC meeting calendar | Public Board website |
| U.S. Treasury | TreasuryDirect upcoming auctions API, Fiscal Data upcoming auctions API (fallback) | Official open APIs, no key |
| Rules | Opex, VIX settlement, NYSE holidays | Computed in code (no data source) |

Each source is fetched once per run, so it adds negligible load. The Actor doesn't use FRED or any commercial calendar.

### FAQ

**Does it include consensus forecasts or actual numbers?** No. Forecasts are proprietary, and actual values arrive at release time. This Actor is a when-and-how-big schedule.

**Does it include company earnings or ex-dividend dates?** No. No official government source publishes forward earnings dates. Use the `ticker` field as a label and pair it with your own earnings data.

**How accurate are the dates?** They're exactly what each agency publishes at fetch time. Agencies sometimes reschedule, for example during a government shutdown. Use alert mode to catch moves.

**Why is a Treasury time marked `timeConfirmed: false`?** Treasury hasn't announced that auction yet, so the row shows the standard competitive close: 11:30 AM ET for bills and FRNs, 1:00 PM ET for notes, bonds and TIPS.

**Are unscheduled market closures included?** No. Rule-computed holidays cover the regular NYSE schedule only. Special closures, such as national days of mourning, can't be predicted.

**What happens if an agency site is down?** That source is skipped with a warning and listed in `RUN_SUMMARY.sourcesFailed`. The other sources still return rows. If every requested source fails, the run fails and nothing is charged.

**How far ahead does it go?** As far as each agency has published. BLS and BEA usually cover the current year and part of the next, Census covers the current and next calendar year, the Fed lists the next year's meetings, and Treasury announces auctions one to two weeks ahead.

**What do I pay?** $0.003 per event row plus $0.00001 per run start. The default run (2 monthly expirations, medium+) is about 55–60 rows, roughly $0.17. A high-impact-only run for one expiration is about 6 rows, under $0.02. Invalid input and failed sources produce no rows and no charge.

**Is BLS CPI's reference month shown?** BLS's calendar file doesn't include it, so `referencePeriod` is null for BLS rows. BEA and Census rows include it.

### Pricing

Pay per event: **$0.003 per event row** (default dataset item) plus **$0.00001 per Actor start**. You pay only for rows delivered.

# Actor input Schema

## `expirations` (type: `array`):

Your option expiration dates as YYYY-MM-DD (for example 2026-11-20). Each date becomes one window: every scheduled event from the start date up to 4:00 PM ET on that expiration is listed with days and trading days before expiration. Leave empty to use 'Next N monthly expirations' instead.

## `nextMonthlyExpirations` (type: `integer`):

Add the next N standard monthly expirations (3rd Friday; the prior trading day if that Friday is an NYSE holiday). Default 2 when no expiration dates are given, otherwise 0. Set 0 with no dates for a plain calendar between the start and end dates.

## `fromDate` (type: `string`):

First day to include (YYYY-MM-DD, ET). Default: now, so events already released today are skipped. Use a past date to review history the agencies still list.

## `toDate` (type: `string`):

Last day to include (YYYY-MM-DD, ET). Caps every window. In calendar mode (no expirations) the default is 30 days after the start date.

## `windowMode` (type: `string`):

fromStart: each expiration's window starts at the start date, so an event before two expirations appears twice (one row each, with its own days-before count). sincePreviousExpiration: windows don't overlap, so each event appears once and you pay for fewer rows.

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

Only include these categories. Leave empty for all.

## `minImpact` (type: `string`):

Editorial tier of how much options implied volatility usually reacts. High: CPI, Employment Situation, FOMC decisions, GDP advance, Personal Income & Outlays (PCE), retail sales, quarterly expiration. Medium adds PPI, JOLTS, ECI, later GDP estimates, housing, durable goods, trade, FOMC minutes, 2-year-and-longer Treasury note/bond auctions, monthly opex, VIX settlement and NYSE holidays. Low adds everything else.

## `sources` (type: `array`):

Official sources to query. Leave empty for all six.

## `ticker` (type: `string`):

A label copied onto every row (for example SPY or your position name) so you can merge results from several runs. It doesn't change which events are returned; this Actor lists market-wide macro events, not company earnings.

## `alertMode` (type: `boolean`):

Remembers events in a named key-value store and writes only events that are new or whose date/time moved since the last run (changeStatus = new or moved). The first run writes everything as new. Use with a schedule.

## `stateStoreName` (type: `string`):

Named key-value store that holds alert state. Use a different name per watchlist or schedule.

## `maxResults` (type: `integer`):

Hard cap on rows written (and so charged) per run.

## Actor input object example

```json
{
  "expirations": [
    "2026-11-20",
    "2026-12-18"
  ],
  "nextMonthlyExpirations": 2,
  "fromDate": "2026-10-19",
  "toDate": "2026-12-31",
  "windowMode": "fromStart",
  "eventTypes": [
    "inflation",
    "employment",
    "fomc",
    "opex"
  ],
  "minImpact": "medium",
  "sources": [
    "BLS",
    "FED",
    "RULES"
  ],
  "ticker": "SPY",
  "alertMode": false,
  "stateStoreName": "event-risk-calendar-state",
  "maxResults": 300
}
```

# Actor output Schema

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

Events in each expiration window (overview view).

## `summary` (type: `string`):

Windows, row counts, and which sources succeeded or failed.

# 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 = {
    "expirations": [],
    "nextMonthlyExpirations": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("xprm-llc/options-event-risk-calendar").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 = {
    "expirations": [],
    "nextMonthlyExpirations": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("xprm-llc/options-event-risk-calendar").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "expirations": [],
  "nextMonthlyExpirations": 2
}' |
apify call xprm-llc/options-event-risk-calendar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xprm-llc/options-event-risk-calendar"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/2mGBlgXvjrzcbb1y7/builds/GewWGpAQIeptLhEzC/openapi.json