---
title: "Volatility surface and skew per symbol"
method: GET
path: "/v1/vol/surface"
tags: ["Tempest"]
---

# Volatility surface and skew per symbol

`GET /v1/vol/surface`

## Request

- Base URL: `https://api.skylit.ai`
- URL: `https://api.skylit.ai/v1/vol/surface`
- Auth: HTTP bearer

Tempest Surface: 30-day 25-delta risk reversal (`rr25_30`) and butterfly
(`bf25_30`), ATM vol, skew percentile over the year and a per-symbol SKEW
index, plus a smile per expiry (`expiries[]`: strikes/deltas and implied vols).
Heavier than the headline readings, so priced as analytics.
Response: `data.symbols[]` has `symbol`, `asOf`, `sessionDate`, `stale` and `surface`.
Symbols Tempest does not cover are listed in `data.missing`. **Cost:** 3 credits per call (up to 10 symbols).

## Query parameters

- `symbols` string, required

## Response `200`

OK.

- VolSymbolsResponse
  - `data` object, required
    - `missing` VolMissing[], required
      - `reason` 'not_covered' | 'no_history', required
      - `symbol` string, required
    - `symbols` VolSymbol[], required
      - `asOf` string, date-time, required
      - `sessionDate` string, date, required
      - `stale` boolean, required: In session, true when the reading is more than 20 minutes old.
      - `symbol` string, required
  - `meta` VolMeta, required
    - `asOf` string, date-time: When Tempest computed the newest value in this response.
    - `attribution` Attribution: Whether and how this response's data may be published. See `/legal/api#sharing`. An Agent or MCP client should never publish data where `shareable` is false, regardless of `shareClass`. `required`, `license`, `shareable` and `shareClass` are always sent on `/v1/options/*` and absent from the short form.
      - `license` 'personal' | 'commercial' | 'connected_app'
      - `required` boolean
      - `shareClass` 'derived' | 'derived_levels_only' | 'raw': "raw" (e.g. option quotes, greeks) must never be auto-published.
      - `shareable` boolean
      - `terms` string, uri
      - `text` string, required
      - `url` string, uri, required
    - `cached` boolean, required
    - `frozen` boolean, required: True while Tempest serves the previous close (outside regular hours).
    - `marketState` 'pre_open' | 'open' | 'post_close' | 'closed', required: US equity session at request time.
    - `module` string, required: Which endpoint answered (iv, cones, screener, ...).
    - `publishedAt` string, date-time: When Tempest last published to the API.
    - `sessionDate` string, date: The trading session (ET) that asOf belongs to. The close state is stamped 15:59 ET and always belongs to its own session.

## Other responses

- `400`: Request validation failed.
- `401`: Missing API key (`unauthorized`), sent by the gateway.
- `402`: Out of credits (`insufficient_credits`).
- `403`: As `Forbidden`, or `not_entitled`: Tempest data is not enabled for this account (it is in preview). Refunded.
- `404`: Unknown symbol, no data available, or none of the requested `expirations` exist for the symbol (`code: expiration_not_found`).
- `429`: Per-minute rate limit exceeded.
- `503`: Tempest data is loading (`warming_up`, with `Retry-After`) or not configured (`unavailable`). Refunded.
- `504`: The request did not finish in time (`gateway_timeout`). Refunded; retry, or narrow the request.

---

[API](https://skmtc.dev/skylit/apis/skylit-public-api.md) · [All operations](https://skmtc.dev/skylit/apis/skylit-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skylit/apis/skylit-public-api/revisions/890b0ea4e6f5?raw)