Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
description: 'Options-analytics API (token surface). Auth: `Authorization: Bearer avmcp_` on every request; tokens are issued to any paid or trial plan from Basic, and each endpoint follows the same tier as the web app. Rate limits: 60/min and 1,000/hr per token, plus a monthly allowance per account measured in upstream data requests, by plan. The remaining counts come back in the X-RateLimit-* and X-Monthly-Budget-Remaining headers on every response, and GET /api/mcp/data/me/usage returns the month''s meter with a per-endpoint breakdown. IV values are percentage points unless a payload says otherwise (`iv_units`). The same endpoints power the ApexVol MCP server for AI assistants: `pipx install apexvol-mcp` (PyPI), setup at https://apexvol.com/mcp. Docs: https://apexvol.com/docs/api.'
title: ApexVol Events and calendars API
version: '1.30'
servers:
- url: https://apexvol.com
security:
- bearerAuth: []
tags:
- name: Events and calendars
paths:
/api/mcp/data/earnings-calendar:
get:
description: 'Upcoming earnings announcements, each annotated with the implied earnings move vs the average absolute move over the last 12 earnings (implied_move, hist_avg_move, move_ratio). implied_move is the expected absolute move (the feed''s one-sigma figure x 0.8, kept as implied_move_sigma) so it shares hist_avg_move''s basis; implied_move_basis says so.
**Query parameters:** days_ahead (default 7; 1 to 90)
**Response shape:**
```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
}
}
```'
operationId: get_earnings_calendar
parameters:
- description: 'How far ahead to look. Range: 1 to 90.'
in: query
name: days_ahead
required: false
schema:
default: 7
maximum: 90
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/GetEarningsCalendarResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: Upcoming earnings announcements, each annotated with the implied earnings move…
tags:
- Events and calendars
/api/mcp/data/economic-calendar:
get:
description: 'Macro economic-event calendar (CPI, FOMC, jobs reports...).
**Query parameters:** from_date (optional, YYYY-MM-DD) · to_date (optional) · country (default US)
**Response shape:**
```json
{
"success": true,
"data": {
"events": [
{
"actual": null,
"change": null,
"change_pct": 0,
"country": "US",
"currency": "USD",
"date": "2026-09-09",
"datetime": "Wed, 09 Sep 2026 16:30:00 GMT",
"estimate": null,
"event": "API Crude Oil Stock Change (Sep/04)",
"impact": "Medium",
"previous": -2.6,
"time": "4:30 PM",
"unit": null
},
{
"actual": null,
"change": null,
"change_pct": 0,
"country": "US",
"currency": "USD",
"date": "2026-09-09",
"datetime": "Wed, 09 Sep 2026 07:00:00 GMT",
"estimate": null,
"event": "MBA 30-Year Mortgage Rate (Sep/04)",
"impact": "Medium",
"previous": 6.79,
"time": "7:00 AM",
"unit": "%"
},
{
"actual": null,
"change": null,
"change_pct": 0,
"country": "US",
"currency": "USD",
"date": "2026-09-10",
"datetime": "Thu, 10 Sep 2026 10:00:00 GMT",
"estimate": 3.99,
"event": "Existing Home Sales (Aug)",
"impact": "High",
"previous": 4.06,
"time": "10:00 AM",
"unit": "M"
}
],
"high_count": 14,
"medium_count": 38,
"success": true,
"total_count": 52
}
}
```'
operationId: get_economic_calendar
parameters:
- description: 'Start. Range: YYYY-MM-DD.'
in: query
name: from_date
required: false
schema:
default: today
format: date
type: string
- description: 'End. Range: YYYY-MM-DD. Default: +14 days.'
in: query
name: to_date
required: false
schema:
format: date
type: string
- description: 'Which calendar. Range: ISO country.'
in: query
name: country
required: false
schema:
default: US
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/GetEconomicCalendarResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: Macro economic-event calendar (CPI, FOMC, jobs reports...)
tags:
- Events and calendars
/api/mcp/data/seasonality/{ticker}:
get:
description: 'Monthly/quarterly seasonality of returns and volatility.
**Query parameters:** years (optional, default 3; 1 to 10)
**Response shape:**
```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
}
}
```'
operationId: get_seasonality_by_ticker
parameters:
- in: path
name: ticker
required: true
schema:
type: string
- description: 'History length. Range: 1 to 10.'
in: query
name: years
required: false
schema:
default: 3
maximum: 10
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/GetSeasonalityByTickerResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: Monthly/quarterly seasonality of returns and volatility
tags:
- Events and calendars
components:
schemas:
GetSeasonalityByTickerResponse:
properties:
analysis_years:
type: integer
best_month:
type: integer
monthly_seasonality:
properties:
'1':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'10':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'11':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'12':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'2':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'3':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'4':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'5':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'6':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'7':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'8':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'9':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
month:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
type: object
quarterly_seasonality:
properties:
'1':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
quarter:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'2':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
quarter:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'3':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
quarter:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
'4':
properties:
avg_return_pct:
type: number
median_return_pct:
type: number
quarter:
type: integer
sample_size:
type: integer
volatility_pct:
type: number
type: object
type: object
success:
type: boolean
ticker:
type: string
timestamp:
type: string
worst_month:
type: integer
type: object
GetEconomicCalendarResponse:
properties:
events:
items:
properties:
actual:
type:
- string
- 'null'
change:
type:
- string
- 'null'
change_pct:
type: integer
country:
type: string
currency:
type: string
date:
type: string
datetime:
type: string
estimate:
type:
- string
- 'null'
event:
type: string
impact:
type: string
previous:
type: number
time:
type: string
unit:
type:
- string
- 'null'
type: object
type: array
high_count:
type: integer
medium_count:
type: integer
success:
type: boolean
total_count:
type: integer
type: object
GetEarningsCalendarResponse:
properties:
earnings:
items:
properties:
cap_group:
type: string
company_name:
type: string
date:
type: string
datetime:
type: string
days_until:
type: integer
eps_actual:
type:
- string
- 'null'
eps_estimate:
type: number
fiscal_quarter:
type:
- string
- 'null'
hist_avg_move:
type: number
implied_move:
type: number
implied_move_basis:
type: string
implied_move_sigma:
type: number
market_cap:
type: number
move_ratio:
type: number
revenue_actual:
type:
- string
- 'null'
revenue_estimate:
type: integer
sector:
type: string
symbol:
type: string
timing:
type: string
updated:
type: string
type: object
type: array
from_date:
type: string
success:
type: boolean
timestamp:
type: string
to_date:
type: string
total_count:
type: integer
type: object
securitySchemes:
bearerAuth:
description: ApexVol API token (avmcp_...) from apexvol.com/account, API Access.
scheme: bearer
type: http