Volatility Context

curl --request GET \
  --url https://api.unusualwhales.com/api/stock/{ticker}/volatility/context \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/stock/{ticker}/volatility/context"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.unusualwhales.com/api/stock/{ticker}/volatility/context', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/stock/{ticker}/volatility/context",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/stock/{ticker}/volatility/context"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/stock/{ticker}/volatility/context")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "date": "2026-09-25T00:00:00.000Z",
  "earnings_date": "2026-10-28T00:00:00.000Z",
  "earnings_report_time": "postmarket",
  "expiry": {
    "dte": 28,
    "earnings_in_expiry": false,
    "expiry": "2026-10-23T00:00:00.000Z",
    "implied_move": 30.58,
    "implied_move_perc": 0.0822,
    "iv": 0.4386
  },
  "iv30": 0.439,
  "iv_percentile": 32.8,
  "iv_rank": 25.46,
  "iv_rv_ratio": 1.009,
  "market": {
    "vix": 14.87,
    "vix3m": 17.93,
    "vix_curve_inverted": false,
    "vix_futures_regime": "contango"
  },
  "rv": 0.435,
  "rv_days": 21,
  "skew": {
    "delta": 25,
    "label": "call_rich",
    "risk_reversal": -0.0221,
    "scaled": -0.0504
  },
  "term_structure": {
    "inverted": true,
    "iv_30d": 0.439,
    "iv_90d": 0.419,
    "regime": "backwardation",
    "slope": -0.0456
  },
  "ticker": "TSLA"
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "payment_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "This API token is paused because the payment for your API subscription failed. Update your card at https://unusualwhales.com/settings. The same token works again once a payment succeeds.",
  "reason": "payment_failed",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

Something went wrong

volatility

Volatility Context

Returns the volatility context for a ticker on one date: 30-day implied volatility with its one-year rank and percentile, realized volatility, the term structure regime (contango, flat or backwardation), the 25-delta skew with a put-rich, flat or call-rich label, the implied move and earnings timing for one expiry, and VIX conditions.

Pass expiry to describe a specific expiry. Without it, the response uses the listed expiry closest to 30 days out. date defaults to the last trading day. A value that has no data is null, never zero.

GET

api

stock

{ticker}

volatility

context

Volatility Context

curl --request GET \
  --url https://api.unusualwhales.com/api/stock/{ticker}/volatility/context \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/stock/{ticker}/volatility/context"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.unusualwhales.com/api/stock/{ticker}/volatility/context', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/stock/{ticker}/volatility/context",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/stock/{ticker}/volatility/context"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/stock/{ticker}/volatility/context")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "date": "2026-09-25T00:00:00.000Z",
  "earnings_date": "2026-10-28T00:00:00.000Z",
  "earnings_report_time": "postmarket",
  "expiry": {
    "dte": 28,
    "earnings_in_expiry": false,
    "expiry": "2026-10-23T00:00:00.000Z",
    "implied_move": 30.58,
    "implied_move_perc": 0.0822,
    "iv": 0.4386
  },
  "iv30": 0.439,
  "iv_percentile": 32.8,
  "iv_rank": 25.46,
  "iv_rv_ratio": 1.009,
  "market": {
    "vix": 14.87,
    "vix3m": 17.93,
    "vix_curve_inverted": false,
    "vix_futures_regime": "contango"
  },
  "rv": 0.435,
  "rv_days": 21,
  "skew": {
    "delta": 25,
    "label": "call_rich",
    "risk_reversal": -0.0221,
    "scaled": -0.0504
  },
  "term_structure": {
    "inverted": true,
    "iv_30d": 0.439,
    "iv_90d": 0.419,
    "regime": "backwardation",
    "slope": -0.0456
  },
  "ticker": "TSLA"
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "payment_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "This API token is paused because the payment for your API subscription failed. Update your card at https://unusualwhales.com/settings. The same token works again once a payment succeeds.",
  "reason": "payment_failed",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

Something went wrong

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

ticker

string

required

A single ticker

Example:

"AAPL"

Query Parameters

date

string

A trading date in the format of YYYY-MM-DD. This is optional and by default the last trading date.

Example:

"2024-01-18T00:00:00.000Z"

expiry

string

Describe this expiry (YYYY-MM-DD) instead of the one closest to 30 days out.

Response

Implied volatility, skew, term structure and market conditions for one ticker on one date.

date

string<date>

The trading day the values describe. It is the latest day with term structure data on or before the requested date.

Example:

"2026-09-25T00:00:00.000Z"

earnings_date

string<date> | null

The next scheduled earnings report on or after date, or null when none is scheduled.

Example:

"2026-10-28T00:00:00.000Z"

earnings_report_time

string | null

When earnings_date reports: premarket, postmarket or unknown. Null when no report is scheduled.

Example:

"postmarket"

expiry

object | null

The requested expiry, or the listed expiry closest to 30 days out when none is requested. The object is null when the requested expiry has no term structure data on date.

Show child attributes

iv30

number | null

30-day implied volatility as a decimal. 0.439 means 43.9%.

Example:

0.439

iv_percentile

number | null

The percentage of days in the past year with a lower 30-day implied volatility.

Example:

32.8

iv_rank

number | null

Where iv30 sits between its one-year low (0) and high (100).

Example:

25.46

iv_rv_ratio

number | null

iv30 divided by rv. Values above 1 mean options are priced above recent realized movement.

Example:

1.009

market

object

Market-wide volatility from the latest available closes. vix_curve_inverted is true when VIX closed above VIX3M. vix_futures_regime compares the front two VIX futures and is contango, flat or backwardation.

Show child attributes

number | null

Realized volatility over the rv_days trading days that ended on or before date, as a decimal.

Example:

0.435

rv_days

integer

Example:

21

skew

object | null

The 25-delta risk reversal for the expiry in expiry. risk_reversal is the 25-delta put implied volatility minus the 25-delta call implied volatility, so a positive value means puts are priced richer. scaled divides it by iv30. label is put_rich when scaled is above 0.06, call_rich when it is below 0, and flat otherwise. The object is null when no risk reversal is recorded for that expiry.

Show child attributes

term_structure

object

Compares 30-day and 90-day implied volatility. slope is iv_90d / iv_30d - 1. regime is contango when iv_90d is more than 1% above iv_30d, backwardation when it is more than 1% below, and flat otherwise. inverted is true when regime is backwardation. Every field is null when either volatility is missing.

Show child attributes

ticker

string

Example:

"TSLA"

Docs

Endpoints

Volatility Context

Authorizations

Path Parameters

Query Parameters

Response