# GET /api/mcp/data/historical-moves/{ticker}

> How big a move does NVDA typically make over 7, 14, 21 and 30 days?

For each horizon returns the average absolute move, the mean and median, the percentiles and the largest up and down moves, from daily closes.

- **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:** Percent.
- **Basis:** Rolling close-to-close returns over each horizon across the history the platform holds.
- **MCP tools:** `get_earnings_move_analysis`
- **Background:** https://apexvol.com/learn/implied-volatility

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `periods` | query | 7,14,21,30 | CSV of 1 to 252, at most 8 | Horizons in trading days. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/historical-moves/NVDA"
```

## 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": {
    "current_price": 230.36,
    "move_analysis": {
      "14d": {
        "avg_abs_move_pct": 5.4003,
        "avg_move_pct": 1.7376,
        "max_down_move_pct": -10.5131,
        "max_up_move_pct": 14.8871,
        "median_move_pct": 1.5093,
        "p10": -6.4665,
        "p25": -3.1976,
        "p75": 6.1163,
        "p90": 9.9673,
        "period_days": 14,
        "std_dev_pct": 6.3057
      },
      "21d": {
        "avg_abs_move_pct": 6.7007,
        "avg_move_pct": 2.7348,
        "max_down_move_pct": -12.588,
        "max_up_move_pct": 19.0191,
        "median_move_pct": 3.3738,
        "p10": -8.3477,
        "p25": -1.921,
        "p75": 8.5737,
        "p90": 11.7969,
        "period_days": 21,
        "std_dev_pct": 7.5251
      },
      "30d": {
        "avg_abs_move_pct": 7.1714,
        "avg_move_pct": 2.1683,
        "max_down_move_pct": -17.841,
        "max_up_move_pct": 15.395,
        "median_move_pct": 2.5263,
        "p10": -10.2469,
        "p25": -4.2495,
        "p75": 8.7686,
        "p90": 11.9596,
        "period_days": 30,
        "std_dev_pct": 8.2063
      },
      "7d": {
        "avg_abs_move_pct": 4.7327,
        "avg_move_pct": 1.1532,
        "max_down_move_pct": -10.7926,
        "max_up_move_pct": 18.5403,
        "median_move_pct": 0.5243,
        "p10": -5.6893,
        "p25": -2.9056,
        "p75": 5.0021,
        "p90": 8.8667,
        "period_days": 7,
        "std_dev_pct": 5.9155
      }
    },
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:32.717088"
  }
}
```

## Fields

- `move_analysis.<days>.avg_abs_move_pct, median_move_pct`: Typical size.
- `move_analysis.<days>.p10, p25, p75, p90`: The distribution.
- `move_analysis.<days>.max_up_move_pct, max_down_move_pct`: The tails.

## 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 does NVDA usually move in 2 weeks?
- What is the 90th percentile 30-day move on AAPL?
- Give me SPY's move distribution at 7 and 21 days.

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