# GET /api/mcp/data/earnings-history/{ticker}

> How much has NVDA moved on each of its last eight reports?

Returns one row per past report with the gap move, EPS estimate and actual, the surprise, IV before and after and the crush, plus averages by direction and by beat or miss.

- **Family:** Earnings and expected move (https://apexvol.com/developers/earnings-expected-move-api)
- **Plan:** Pro and above. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access.
- **Units:** Moves in percent and dollars; IVs in percentage points; surprise_pct in percent.
- **Basis:** The move is the previous close to the next open (the gap), not close to close.
- **MCP tools:** `analyze_earnings_history`
- **Background:** https://apexvol.com/learn/earnings-trading-guide

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `num_quarters` | query | 8 | 1 to 40 | How many reports. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/earnings-history/NVDA?num_quarters=8"
```

## 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_moves": [
      {
        "direction": "up",
        "earnings_date": "2026-08-26",
        "eps_actual": 2.22,
        "eps_estimate": 2.09,
        "gap_move_dollar": 13.2,
        "gap_move_pct": 6.2959,
        "iv_after": null,
        "iv_before": null,
        "iv_crush": null,
        "iv_crush_pct": null,
        "next_open": 222.86,
        "prev_close": 209.66,
        "surprise_direction": "beat",
        "surprise_pct": 6.2201,
        "timing": "AMC"
      },
      {
        "direction": "down",
        "earnings_date": "2026-05-20",
        "eps_actual": 1.87,
        "eps_estimate": 1.76,
        "gap_move_dollar": -1.18,
        "gap_move_pct": -0.5287,
        "iv_after": null,
        "iv_before": null,
        "iv_crush": null,
        "iv_crush_pct": null,
        "next_open": 222.03,
        "prev_close": 223.21,
        "surprise_direction": "beat",
        "surprise_pct": 6.25,
        "timing": "AMC"
      },
      {
        "direction": "down",
        "earnings_date": "2026-02-25",
        "eps_actual": 1.62,
        "eps_estimate": 1.54,
        "gap_move_dollar": -1.29,
        "gap_move_pct": -0.6605,
        "iv_after": null,
        "iv_before": null,
        "iv_crush": null,
        "iv_crush_pct": null,
        "next_open": 194.03,
        "prev_close": 195.32,
        "surprise_direction": "beat",
        "surprise_pct": 5.1948,
        "timing": "AMC"
      }
    ],
    "statistics": {
      "avg_abs_move_pct": 2.9618,
      "avg_beat_move_pct": 2.557,
      "avg_down_move_pct": -0.5397,
      "avg_iv_crush_pct": null,
      "avg_miss_move_pct": null,
      "avg_move_pct": 2.557,
      "avg_up_move_pct": 4.415,
      "beat_count": 8,
      "down_count": 3,
      "max_down_pct": -0.6605,
      "max_up_pct": 6.2959,
      "median_iv_crush_pct": null,
      "miss_count": 0,
      "total_earnings": 8,
      "up_count": 5
    },
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T07:49:39.004196"
  }
}
```

## Fields

- `earnings_moves[].earnings_date, gap_move_pct, direction`: The move per report.
- `earnings_moves[].eps_estimate, eps_actual, surprise_pct`: The surprise.
- `earnings_moves[].iv_before, iv_after, iv_crush_pct`: The crush.
- `statistics.avg_abs_move_pct, avg_up_move_pct, avg_down_move_pct, beat_count`: The summary.

## Errors

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

## Ask it in an MCP client

- How much has NVDA moved on its last 8 earnings?
- What is AAPL's average earnings gap?
- Show TSLA's earnings surprises and the moves that followed.

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