# GET /api/mcp/data/seasonality/{ticker}

> Which months have historically been strongest and weakest for NVDA?

Returns per-month and per-quarter average and median returns with the sample size and volatility over the requested years, plus the best and worst months.

- **Family:** Events and calendars (https://apexvol.com/developers/events-calendar-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:** Returns and volatility in percent.
- **Basis:** Monthly close-to-close returns over analysis_years.
- **MCP tools:** `get_earnings_move_analysis`
- **Background:** https://apexvol.com/learn/volatility-trading

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `years` | query | 3 | 1 to 10 | History length. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/seasonality/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": {
    "analysis_years": 3,
    "best_month": 5,
    "monthly_seasonality": {
      "1": {
        "avg_return_pct": 0.2741,
        "median_return_pct": 0.471,
        "month": 1,
        "sample_size": 61,
        "volatility_pct": 3.4418
      },
      "2": {
        "avg_return_pct": 0.4343,
        "median_return_pct": 0.3508,
        "month": 2,
        "sample_size": 58,
        "volatility_pct": 3.6276
      },
      "3": {
        "avg_return_pct": 0.0074,
        "median_return_pct": 0.1223,
        "month": 3,
        "sample_size": 63,
        "volatility_pct": 3.0692
      },
      "4": {
        "avg_return_pct": 0.2274,
        "median_return_pct": 0.2521,
        "month": 4,
        "sample_size": 64,
        "volatility_pct": 4.0456
      },
      "5": {
        "avg_return_pct": 0.8471,
        "median_return_pct": 0.4241,
        "month": 5,
        "sample_size": 63,
        "volatility_pct": 2.6655
      },
      "6": {
        "avg_return_pct": 0.4123,
        "median_return_pct": 0.3537,
        "month": 6,
        "sample_size": 60,
        "volatility_pct": 2.7239
      },
      "7": {
        "avg_return_pct": 0.1496,
        "median_return_pct": 0.2925,
        "month": 7,
        "sample_size": 66,
        "volatility_pct": 3.1089
      },
      "8": {
        "avg_return_pct": 0.1925,
        "median_return_pct": -0.0426,
        "month": 8,
        "sample_size": 64,
        "volatility_pct": 3.0437
      },
      "9": {
        "avg_return_pct": 0.1875,
        "median_return_pct": 0.2386,
        "month": 9,
        "sample_size": 59,
        "volatility_pct": 2.6006
      },
      "10": {
        "avg_return_pct": 0.1858,
        "median_return_pct": 0.5626,
        "month": 10,
        "sample_size": 68,
        "volatility_pct": 2.431
      },
      "11": {
        "avg_return_pct": 0.0999,
        "median_return_pct": 0.3984,
        "month": 11,
        "sample_size": 60,
        "volatility_pct": 2.3957
      },
      "12": {
        "avg_return_pct": 0.1453,
        "median_return_pct": 0.2031,
        "month": 12,
        "sample_size": 63,
        "volatility_pct": 1.8841
      }
    },
    "quarterly_seasonality": {
      "1": {
        "avg_return_pct": 0.2328,
        "median_return_pct": 0.364,
        "quarter": 1,
        "sample_size": 182,
        "volatility_pct": 3.3659
      },
      "2": {
        "avg_return_pct": 0.4955,
        "median_return_pct": 0.2593,
        "quarter": 2,
        "sample_size": 187,
        "volatility_pct": 3.2147
      },
      "3": {
        "avg_return_pct": 0.176,
        "median_return_pct": 0.2371,
        "quarter": 3,
        "sample_size": 189,
        "volatility_pct": 2.9211
      },
      "4": {
        "avg_return_pct": 0.1455,
        "median_return_pct": 0.3515,
        "quarter": 4,
        "sample_size": 191,
        "volatility_pct": 2.2418
      }
    },
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:50.837273",
    "worst_month": 3
  }
}
```

## Fields

- `monthly_seasonality.<month>.avg_return_pct, median_return_pct, volatility_pct, sample_size`: Per month.
- `quarterly_seasonality.<quarter>`: Per quarter.
- `best_month, worst_month`: The extremes.

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

- What is NVDA's seasonality by month?
- Is September usually weak for SPY?
- Which quarter has been best for AAPL over 5 years?

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