Skip to content

API Workflow Overview

Reflex Research exposes multiple datasets via an API. This page explains the intended workflow.

Two classes of datasets

At a high level, Reflex Research provides:

  • Options-derived datasets.
  • Jobs datasets.

Understanding which category a dataset belongs to determines how you should interact with the API.

Options-derived datasets

The following datasets are derived from options markets:

  • Breeden–Litzenberger PDFs (BL).
  • Gamma Exposure (GEX).
  • VIXnD.

The options are:

  • Discrete in strike.
  • Discrete in expiry.
  • Observed at irregular measurement times.

As a result, the datasets inherit that structure. All options-derived datasets share the same discovery and retrieval workflow.

The API is designed to be traversed in stages.

1. Select a metric

Each request begins by choosing a metric. This is the model you want a measurement of:

  • bl.
  • gex.
  • vixnd.

2. Discover available tickers for the metric.

The tickers are the identifier for the index or company. Given the metric has been chosen, the available tickers needs to be obtained.

GET /v1/{metric}/tickers

3. Discover available expiries for the metric and ticker.

Now that the metric and ticker have been chosen, the expiration dates available to get measurements for need to be obtained. The timestamps are in UNIX epoch seconds, UTC.

GET /v1/{metric}/{ticker}/expiries

4. Discover available measurement times for the metric, ticker and expiry.

For a given metric, ticker and expiry, the list of measurement times needs to be obtained. This is typically used to gather historic data for analysis. Essentially, at each measurement time, the data downloaded for the given expiry represents a snapshot of the data at the measurement time. The timestamps are in UNIX epoch seconds, UTC.

GET /v1/{metric}/{ticker}/{expiry}/measurements

5. Get a specific measurement for the metric, ticker, expiry and measurement time.

All of the input data is now avaialble to obtain a data snapshot. The return is a JSON organised data set.

GET /v1/{metric}/{ticker}/{expiry}/{measurement_time}

6. Get the latest measurement for the metric, ticker and expiry.

Sometimes it is required that just the latest data set is needed, without going through the process of obtaining measurement times. This endpoint delivers the latest snapshot, and includes the measurement time in the data.

GET /v1/{metric}/{ticker}/{expiry}/latest

Example common Python code.

With the examples in other pages, they will all assume some common code. These are some suggested examples.

# pip install requests
import requests
from typing import Any, Dict

# Base URL for the Reflex Research derived data API.
API_BASE_URL = "https://data.reflex-research.com"
# Your personal API key. This key is required for all authenticated endpoints. 
# The key supplied to you must be available as a string in the program.
API_KEY = "******"

# Standard headers used for all API requests. Authentication is handled via the
# X-API-Key header.
HEADERS = {
    "X-API-Key": API_KEY,
}

def get_json(
    url: str,
) -> Dict[str, Any]:
    """
    Perform a GET request and return the decoded JSON response.

    This helper function:
    - Applies authentication headers.
    - Enforces a reasonable timeout.
    - Raises an exception for non-200 responses.
    """
    response = requests.get(url, headers=HEADERS, timeout=10)
    response.raise_for_status()
    return response.json()

def get_measurement(
    metric: str,
    ticker: str,
    expiry: str,
    measurement_time: str,
) -> Dict[str, Any]:
    """
    Retrieve a specific measurement for a given metric, ticker, option expiry
    and measurement timestamp.

    A measurement represents a deterministic, point-in-time snapshot of the
    selected metric. Providing the same inputs will always return the same
    dataset, making this endpoint suitable for backtesting, research, and
    reproducible analysis.

    All time-related values used by the API are expressed as UNIX epoch time
    in seconds, UTC.

    Typical compressed payload sizes are on the order of 5-20 kB per
    measurement.

    Args:
        metric (str): The metric identifier, "bl", "gex" or "vixnd".
        ticker (str): The underlying ticker symbol, e.g. "AAPL", "SPXW".
        expiry (str): The option expiry timestamp, expressed as UNIX epoch time
            in seconds, UTC.
        measurement_time (str): The timestamp at which the measurement was
            taken, expressed as UNIX epoch time in seconds, UT).

    Returns:
        dict: A JSON object containing the requested measurement data. The
            structure of the returned data depends on the selected metric.
    """
    url = f"{API_BASE_URL}/v1/{metric}/{ticker}/{expiry}/{measurement_time}"
    return get_json(url) 

def list_expiries(
    metric: str,
    ticker: str,
) -> List[int]:
    """
    Retrieve available expiries for a given metric and ticker.
    """
    url = f"{API_BASE_URL}/v1/{metric}/{ticker}/expiries"
    data = get_json(url)
    return data["expiries"]

def get_latest_measurement(
    metric: str,
    ticker: str,
    expiry: int,
) -> Dict[str, Any]:
    """
    Retrieve the latest measurement for a given metric, ticker, and expiry.
    """
    url = f"{API_BASE_URL}/v1/{metric}/{ticker}/{expiry}/latest"
    return get_json(url)

def select_nearest_future_expiry(
    expiries: List[int],
) -> int:
    """
    Select the nearest expiry strictly in the future.
    """
    now = int(time.time())
    future_expiries = [e for e in expiries if e > now]

    if not future_expiries:
        raise ValueError("No future expiries available.")

    return min(future_expiries)

As a simple test to check you have a connection to Reflex Research, test the health endpoint:

def health_check() -> Dict[str, Any]:
    """
    Check that the API service is reachable and responding correctly.

    This endpoint is typically used to:
    - Verify connectivity.
    - Confirm the API service is alive before making data requests.
    """
    url = f"{API_BASE_URL}/v1/health"
    return get_json(url)

if __name__ == "__main__":
    # Run the health check when the script is executed directly. If this fails,
    # no other API calls will succeed. Should return {'status': 'ok'}.
    result = health_check()
    print(result)

Jobs datasets

This section is still under construction.