research

Endpoint Overview

The Research API computes on-demand Greek exposures, volatility surfaces, open interest profiles, and price-spread parity. It serves index options, ETFs, and all US optionable equities.

GET /research/{ticker}/{metric}

Architecture & Service Base URLs

• API Gateway: /research/{ticker}/{metric}
• Asset Storage & CDN: https://assets.gexbot.com/ (or https://r.gex.bot/). The url field of a descriptor already starts with gbR/.

Operating Hours & Data Cadence

• Regular Market Hours (09:30–16:00 ET):
  • Evaluates live option market quotes using the gbR pricing model.
  • Caches requests on 15-minute floor intervals on-demand.
• Index Option Extended Hours (16:00–16:15 ET):
  • Index options (such as SPX and NDX) trade until 16:15 ET.
  • Requests submitted at or after 16:15 ET include trades from this 15-minute post-close window.
• Premarket Hours (Before 09:30 ET):
  • Open Interest (OI) refreshes daily at 08:00 ET.
  • Calculations use previous session quotes under the gbR model. The premarket cache refreshes once after 08:00 ET.
  • Option volume metrics remain disabled until market open at 09:30 ET.
• After Hours, Final Snapshots & Weekends:
  • The final scheduled End-of-Day (EOD) snapshot generates every evening at 23:00 UTC (19:00 EDT / 18:00 EST).
  • After 17:00 ET, all after-hours queries return the stabilized closing snapshot from the session.
  • Queries on weekends and market holidays return the cached snapshot from the previous trading session.

Option Expiration & Settlement Cadence

• Settlement Timestamps:
  • AM-Settled Series: Standard monthly index contracts expire at 10:00 ET on their expiration date.
  • PM-Settled Series: Daily and weekly equity and index contracts expire at 16:00 ET on their expiration date.
• Expired Series Filtering:
  • Contracts drop immediately from active expirations and calculations once the market clock reaches their expiration timestamp.
  • DTE resolution, exposure metrics, and API responses exclude expired contracts automatically.

Authentication & Headers

All requests require a Research API key (prefix research_). You can create one when your account has the Research add-on. The endpoint refuses gexbot keys, including Quant keys, with 403. Pass the key in the Authorization header as a Bearer token:

Authorization: Bearer <YOUR_API_KEY>
User-Agent: <YOUR_APP_NAME>/1.0
Accept: application/json

Path Parameters

Metric Aliases

The API translates legacy and shorthand metric names to internal engines. Metric names are not case-sensitive.

Query Parameters

The view and type values are case-sensitive. All other values are not. Only the value true (any case) turns a boolean on. Any other value is false. A start_dte or end_dte value that is not an integer resets both parameters to their defaults. For chart formats an empty expiration window moves to the nearest expiration.

Response Schemas

1. Image Asset Descriptor Response

When format is webp, png, svg, jpeg, or pdf, the server returns a JSON object containing the relative asset URL:

{
  "url": "gbR/QUFQTF9za2V3X2NvbnRyYWN0X2FnZ18yMDI2MDcwOFQxNTQ4MDU.svg",
  "name": "QUFQTF9za2V3X2NvbnRyYWN0X2FnZ18yMDI2MDcwOFQxNTQ4MDU.svg",
  "content_type": "image/svg+xml",
  "description": "$AAPL skew 20260708T154805",
  "time_stamp": "20260708T154805",
  "model_ts": "2026-07-08T15:45:00-04:00",
  "model": "gbR"
}

2. Tabular Data Response (format=csv and format=json)

When format=csv the endpoint returns text/csv with Content-Disposition: attachment; filename="SPX_data.csv". When format=json it returns application/json: an array of row objects with the same columns, with Content-Disposition: attachment; filename="SPX_data.json".

• Skew view columns: idx_strike_price, idx_expiration_date (absent when expiry_agg=true), idx_call_put_flag (absent when contract_agg=true, the default) and the metric id in upper case, for example GEX_OI.
• Term view columns: idx_expiration_date, idx_call_put_flag (absent when contract_agg=true) and the metric.
• Surface view: one row per strike and expiration with the metric.
• gamma_flip, vol_trigger, gamma_wall and gamma_wall_abs return the gamma-flip table instead.
• skew_adj and expiration_filter have no effect on csv or json output.

Example header with contract_agg=false:

idx_strike_price,idx_expiration_date,idx_call_put_flag,GEX_OI

Error Handling & Rate Limits

Code Examples

BASE_URL="<your host and version>"

# Request SVG chart asset descriptor
curl -X GET "$BASE_URL/research/SPX/gex_oi?format=svg&strikes=25&contract_agg=true" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "User-Agent: MyResearchApp/1.0" \
  -H "Accept: application/json"

# Request raw CSV dataset
curl -X GET "$BASE_URL/research/AAPL/gex_oi?format=csv&start_dte=0&end_dte=30" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "User-Agent: MyResearchApp/1.0" \
  -H "Accept: text/csv"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "<your host and version>"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "User-Agent": "PythonClient/1.0",
    "Accept": "application/json",
}

# Fetch chart asset descriptor
url = f"{BASE_URL}/research/NVDA/iv_mid"
params = {
    "format": "webp",
    "view": "term",
    "start_dte": 0,
    "end_dte": 180
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
image_url = f"https://assets.gexbot.com/{data['url']}"
print(f"Chart available at: {image_url}")

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = '<your host and version>';

async function fetchResearchCSV(ticker: string, metric: string) {
  const url = new URL(`${BASE_URL}/research/${ticker}/${metric}`);
  url.searchParams.set('format', 'csv');
  url.searchParams.set('start_dte', '0');
  url.searchParams.set('end_dte', '98');

  const res = await fetch(url.toString(), {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'User-Agent': 'NodeApp/1.0',
      'Accept': 'text/csv',
    },
  });

  if (!res.ok) {
    throw new Error(`Request failed with status ${res.status}`);
  }

  const csvData = await res.text();
  return csvData;
}