Options Aggregates API Guide

An options aggregate is a compressed view of qualifying trades in a fixed time interval. For each interval, the response gives the open, high, low, close, volume, VWAP, timestamp, and trade count. This makes aggregates the natural input for charts, historical price paths, volume studies, and many first-pass backtests. They answer: what prices actually printed, how much volume traded, and how the contract moved over the selected bar width.

Aggregates are not the same as quotes. A bar can show where trades occurred without proving that a strategy could have bought at the low, sold at the high, or crossed the midpoint. For execution-sensitive research, use aggregate bars to define the path and quotes to validate fill assumptions. This separation keeps the research design honest: one dataset describes prints, the other describes available markets.

# Custom range bars
curl "https://api.cutemarkets.com/v1/options/aggs/O:SPY260515C00500000/5/minute/2026-05-01/2026-05-15/?limit=10000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# One daily open-close snapshot
curl "https://api.cutemarkets.com/v1/options/open-close/O:SPY260515C00500000/2026-05-12/" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Previous completed session
curl "https://api.cutemarkets.com/v1/options/aggs/O:SPY260515C00500000/prev/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Aggregates are useful for defining candidate entry and exit times. For example, a 5-minute opening-range strategy can read 5-minute bars, identify the first range after the market opens, and measure whether the option contract later traded through a trigger level. This is the right first layer because it works on observed trade prices and can be computed efficiently across many contracts.

The second layer should be quote validation. If a backtest enters at a printed close without checking the bid-ask spread, it can overstate performance in thin contracts. A more defensible design uses aggregate bars to discover candidate moments, then queries quotes around those timestamps to estimate realistic fills, reject wide-spread contracts, and measure slippage sensitivity.

A dashboard does not always need every trade tick. Aggregates can show the shape of the contract: where it opened, where it traded, whether volume is arriving, and whether the current bar is unusual compared with recent bars. This is especially useful for watchlists where dozens of contracts need a compact, comparable representation.

For dashboard stability, keep the bar width aligned with the user decision. One-minute bars are useful for active monitoring but noisy for slower research. Five-minute or fifteen-minute bars often give a cleaner view of option movement while still responding quickly enough for scanners and alert systems.

Event studies need consistent windows. Aggregates make it straightforward to pull bars before and after an event, compute return paths, compare volume profiles, and normalize the result across contracts. A clean study might compare the same moneyness bucket across several expirations, then measure how the bar path changes before and after the event timestamp.

The key is to avoid survivorship by starting from historical contract discovery. Find the contracts that were listed as of the event date, choose expirations and strikes by a pre-declared rule, then pull aggregate bars only for those contracts. That keeps the study from accidentally selecting contracts that look liquid only after the event is already known.

Option VWAP is a compact activity feature. It can help distinguish a contract that prints once at an odd price from one that trades repeatedly near a stable level. When paired with trade count and volume, VWAP can become a quality filter before a scanner spends quota on deeper quote or snapshot checks.

A practical scanner can rank contracts by fresh volume, compare the latest close to intraday VWAP, then require a minimum trade count. This does not prove the signal is profitable, but it improves the measurement surface by excluding contracts where a single stale or isolated print dominates the bar.

Daily bars are useful for explaining what happened, even when the actual execution logic runs on quotes or trades. A daily report can show the previous close, current open, high, low, close, volume, and VWAP for each monitored contract. This gives product users a compact audit trail for why a position or watchlist item changed.

The previous-day endpoint is the fastest path when the dashboard only needs a baseline. It avoids scanning a date range and returns the last completed daily bar directly. For larger historical reports, the range endpoint remains the better choice because it gives consistent pagination and explicit date windows.

The clean sequence is expiration discovery, contract selection, aggregate retrieval, and optional quote validation. Each stage narrows the question. The expiration endpoint prevents invalid dates, the contracts endpoint gives concrete OCC symbols, aggregate bars describe the trade path, and quotes validate execution assumptions around the timestamps that matter.

# 1. Find listed expirations
curl "https://api.cutemarkets.com/v1/tickers/expirations/SPY/" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Select contracts for one expiration
curl "https://api.cutemarkets.com/v1/options/contracts/?underlying_ticker=SPY&expiration_date=2026-05-15&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Pull bars for the selected OCC ticker
curl "https://api.cutemarkets.com/v1/options/aggs/O:SPY260515C00500000/5/minute/2026-05-01/2026-05-15/?limit=10000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 4. Validate candidate fills with quote history
curl "https://api.cutemarkets.com/v1/options/quotes/O:SPY260515C00500000/?timestamp.gte=2026-05-15T13:30:00Z&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"