# GET /api/mcp/data/earnings-calendar

> Who reports this week, and which names have the biggest move priced in?

Lists reports over the next days_ahead with timing, estimates, the implied earnings move, the average move over the last twelve reports and the ratio of the two, plus a day grid for display.

- **Family:** Events and calendars (https://apexvol.com/developers/events-calendar-api)
- **Plan:** Basic and above. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access.
- **Units:** implied_move and hist_avg_move in percent (expected absolute move); market_cap in dollars.
- **Basis:** implied_move is the feed's one-sigma figure times 0.8 so it shares hist_avg_move's basis; implied_move_basis says so and implied_move_sigma keeps the raw figure.
- **MCP tools:** `get_earnings_calendar`
- **Background:** https://apexvol.com/learn/earnings-trade-checklist

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `days_ahead` | query | 7 | 1 to 90 | How far ahead to look. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/earnings-calendar?days_ahead=7"
```

## Response (captured 2026-09-08)

Real response, lists cut to the rows nearest the money. The envelope is `{"success": true, "data": ...}`.

```json
{
  "success": true,
  "data": {
    "earnings": [
      {
        "cap_group": "large",
        "company_name": "Kroger Co.",
        "date": "2026-09-11",
        "datetime": "Fri, 11 Sep 2026 00:00:00 GMT",
        "days_until": 3,
        "eps_actual": null,
        "eps_estimate": 1.05,
        "fiscal_quarter": null,
        "hist_avg_move": 4.72,
        "implied_move": 3.87,
        "implied_move_basis": "expected_abs_move",
        "implied_move_sigma": 4.84,
        "market_cap": 35876625000.0,
        "move_ratio": 0.82,
        "revenue_actual": null,
        "revenue_estimate": 34641620000,
        "sector": "Consumer Staples",
        "symbol": "KR",
        "timing": "BMO",
        "updated": "2026-09-08"
      },
      {
        "cap_group": "mega",
        "company_name": "Oracle Corporation",
        "date": "2026-09-10",
        "datetime": "Thu, 10 Sep 2026 00:00:00 GMT",
        "days_until": 2,
        "eps_actual": null,
        "eps_estimate": 1.74,
        "fiscal_quarter": null,
        "hist_avg_move": 12.5,
        "implied_move": 8.02,
        "implied_move_basis": "expected_abs_move",
        "implied_move_sigma": 10.03,
        "market_cap": 456554654000.0,
        "move_ratio": 0.64,
        "revenue_actual": null,
        "revenue_estimate": 19131390000,
        "sector": "Technology",
        "symbol": "ORCL",
        "timing": "AMC",
        "updated": "2026-09-08"
      },
      {
        "cap_group": "mid",
        "company_name": "",
        "date": "2026-09-08",
        "datetime": "Tue, 08 Sep 2026 00:00:00 GMT",
        "days_until": 0,
        "eps_actual": null,
        "eps_estimate": 0.612,
        "fiscal_quarter": null,
        "hist_avg_move": 13.76,
        "implied_move": 8.36,
        "implied_move_basis": "expected_abs_move",
        "implied_move_sigma": 10.45,
        "market_cap": 2654975000.0,
        "move_ratio": 0.61,
        "revenue_actual": null,
        "revenue_estimate": 7705088000,
        "sector": "",
        "symbol": "UNFI",
        "timing": "TBD",
        "updated": "2026-09-08"
      }
    ],
    "from_date": "2026-09-08",
    "success": true,
    "timestamp": "2026-09-08T08:07:48.281034",
    "to_date": "2026-09-15",
    "total_count": 12
  }
}
```

## Fields

- `earnings[].symbol, company_name, date, timing`: Who and when.
- `earnings[].implied_move, hist_avg_move, move_ratio`: Priced versus typical.
- `earnings[].eps_estimate, revenue_estimate, market_cap, sector`: Context.
- `total_count, from_date, to_date`: The window.

## Errors

- `401`: no or revoked token
- `429`: Retry-After seconds
- `424`: data feed unavailable, retry
- Full list: https://apexvol.com/developers/errors

## Ask it in an MCP client

- Who reports earnings this week with the biggest implied move?
- List next week's large-cap earnings.
- Which reports in the next 3 days have a move ratio above 1.2?

Conventions for units, bases and timestamps: https://apexvol.com/developers/conventions