---
title: "Per-contract volume vs rolling baseline (unusual options activity)"
method: GET
path: "/api/v1/options/{symbol}/unusual-volume"
tags: ["Options"]
---

# Per-contract volume vs rolling baseline (unusual options activity)

`GET /api/v1/options/{symbol}/unusual-volume`

Derived endpoint that flags contracts whose current per-contract volume materially exceeds the contract's own rolling average across the last ``baseline_window_days`` dated snapshots. Walks the latest B6 snapshot's per-contract volumes; for each contract (both calls and puts) computes ``baseline_avg = mean(volume across days the contract appeared with positive volume)`` and flags rows where ``current_volume / baseline_avg > threshold``. Per-row output carries OSI contract symbol + strike + expiry + current volume + baseline + ratio + supplementary Greeks (delta + IV). Sorted by ratio DESC; truncated to ``limit``. Use case: ``UC-4 Insider + Options Flow Confluence`` - bullish skew detection in concert with Form 4 insider purchases.

## Path parameters

- `symbol` string, required — Underlier ticker.

## Query parameters

- `threshold` number — Volume-ratio threshold for the unusual flag (1.5..50). Default 3.0 = 3x the contract's rolling average.
- `limit` integer — Maximum flagged contracts returned (1..200).
- `baseline_window_days` integer — Rolling baseline window in calendar days (5..90). Defaults to 30. Bounded by 90-day retention.
- `min_volume` integer — Minimum current-snapshot volume for a contract to be evaluated (filters illiquid deep-OTM strikes).
- `min_baseline_days` integer — Minimum baseline coverage (days the contract appeared with positive volume) required for a contract to qualify. Contracts below this floor land in contracts_excluded_no_baseline.

## Response `200`

Unusual options activity payload.

- EnvelopeOptionsUnusualVolumePayload
  - `data` OptionsUnusualVolumePayload, required — UC-4.5 derived endpoint: contracts with current volume well above their own recent average. Walks the latest B6 snapshot's per-contract volumes and compares each contract to a rolling baseline computed across the last N dated snapshots. Contracts where `current_volume / baseline_avg_volume` exceeds the threshold are flagged; results sorted by ratio DESC. Methodology limits (v1): - Baseline uses per-contract volume on days where the contract was present with positive volume. Contracts that didn't exist (newly- listed) or had zero volume on some days contribute a SHORTER baseline_days_count but still get a baseline_avg over the days they had volume; `min_baseline_days` query param controls the minimum coverage for a contract to qualify. - `current_volume` floor (`min_volume` query) filters noise from sparsely-traded deep-out-of-money strikes. - Daily granularity from B6 snapshot cadence — no intraday volume bursts captured. - PUT and CALL both included (this is a volume-burst signal, not a direction signal); callers can filter by `option_type` client-side.
    - `symbol` string, required
    - `snapshot_date` string, required
    - `underlier_price` number, nullable
    - `threshold` number, required — Echoed ratio threshold; contracts with volume_ratio > threshold are flagged.
    - `baseline_window_days` integer, required — Echoed baseline lookback window.
    - `baseline_snapshots_loaded` integer, required — Actual count of historical snapshots loaded for the baseline (≤ baseline_window_days; less when ingest hasn't filled the full window yet).
    - `min_volume` integer, required — Echoed current-volume floor.
    - `min_baseline_days` integer, required — Echoed minimum baseline-coverage floor.
    - `contracts_evaluated` integer, required — Contracts in the latest snapshot considered after floors applied.
    - `contracts_excluded_no_baseline` integer, required — Contracts excluded because baseline_days_count < min_baseline_days.
    - `unusual_count` integer, required — Contracts whose volume_ratio > threshold.
    - `unusual_contracts` OptionsUnusualContract[], required — Flagged contracts sorted by volume_ratio DESC then current_volume DESC.
      - `contract_symbol` string, required — OCC OSI contract symbol from the snapshot.
      - `option_type` string, required — C for call, P for put.
      - `strike` number, nullable
      - `expiry` string, required — Expiration date (YYYY-MM-DD).
      - `current_volume` integer, required — Today's contract volume (current snapshot).
      - `baseline_avg_volume` number, required — Arithmetic mean of contract volume across the baseline window days where the contract appeared with positive volume.
      - `baseline_days_count` integer, required — Number of historical days the contract was found in the baseline window (max = baseline_window_days). Lower count = weaker baseline.
      - `volume_ratio` number, required — current_volume / baseline_avg_volume. Higher = more unusual relative to the contract's own recent average.
      - `open_interest` integer, nullable
      - `implied_volatility` number, nullable
      - `delta` number, nullable
      - `in_the_money` boolean, nullable
    - `data_source` string, nullable — Provenance of the underlying B6 snapshot blob. Exchange-direct options for VIX (live, native Greeks). Legacy commercial equity options path for ~199 equity underliers - stale-by-design since DATA-N1 disabled that ingest. Compare ``as_of`` against today to gauge freshness. Wire tokens are stable identifiers, not brand names.
    - `as_of` string, nullable — ISO-8601 timestamp of when the underlying snapshot blob was taken (``snapshot_taken_at`` in the blob). For DATA-N1-skipped underliers this is the last good upstream cycle before disable.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/dcf7427e6897/schema)