# Contracts with unusual relative volume

`GET https://flow-api.skylit.ai/v1/contract/unusual-volume`

API: Flowseeker. Credits: 3.

Contracts whose volume on the target date is anomalously high
relative to a `avgPeriod`-day baseline. Filters cover RVOL, raw
volume, OI dynamics, premium, IV, moneyness, sweep / multi-leg,
and ticker include / exclude lists. Sortable by `rvol`, `volume`,
`premium`, `vol_oi`, or `oi_change`.

## Authentication

Send your Skylit API key as a bearer token: `Authorization: Bearer <key>`. No other header is accepted.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Maximum rows to return. (default `50`; min 1; max 200) |
| `min_rvol` | query | number (double) | no |  (default `2`) |
| `avg_period` | query | string | no | Baseline window as `{N}d`. Must be 2–365 days. (default `10d`) |
| `min_avg_volume` | query | integer | no |  (default `100`; min 0) |
| `min_premium` | query | number (double) | no |  |
| `ticker` | query | string | no |  |
| `right` | query | string | no |  (one of `C`, `P`) |
| `min_dte` | query | integer | no |  |
| `max_dte` | query | integer | no |  |
| `min_strike` | query | number (double) | no |  |
| `max_strike` | query | number (double) | no |  |
| `expiration` | query | string (date) | no |  |
| `date` | query | string (date) | no | Target trading date (`YYYY-MM-DD`). Defaults to the **previous calendar day** (not the current trading date) since baselines need a settled session. |
| `order_by` | query | string | no |  (one of `rvol`, `volume`, `premium`, `vol_oi`, `oi_change`; default `rvol`) |
| `min_vol_oi_ratio` | query | number (double) | no |  |
| `min_oi_change` | query | integer | no |  |
| `max_oi_change` | query | integer | no |  |
| `only_sweeps` | query | boolean | no |  |
| `only_multi_leg` | query | boolean | no |  |
| `exclude_multi_leg` | query | boolean | no |  |
| `min_oi_change_pct` | query | number (double) | no |  |
| `min_bid_imbalance` | query | number (double) | no |  (min 0; max 1) |
| `min_ask_imbalance` | query | number (double) | no |  (min 0; max 1) |
| `moneyness` | query | string | no |  (one of `ITM`, `ATM`, `OTM`) |
| `min_moneyness_pct` | query | number (double) | no |  |
| `max_moneyness_pct` | query | number (double) | no |  |
| `min_iv` | query | number (double) | no |  |
| `max_iv` | query | number (double) | no |  |
| `exclude_tickers` | query | string | no | Comma-separated tickers to exclude (e.g. `SPY,QQQ,IWM`). |

## Example request

```bash
curl "https://flow-api.skylit.ai/v1/contract/unusual-volume" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

## Responses

### 200

Contracts ranked by the requested metric.

Shape (placeholder values):

```json
{
  "data": [
    {
      "symbol": "string",
      "ticker": "string",
      "expiration": "string",
      "strike": 0,
      "right": "C",
      "dte": 0,
      "date": "string",
      "volume": 0,
      "avgVolume": 0,
      "rvol": 0,
      "premium": 0,
      "openInterest": 0,
      "prevOi": 0,
      "oiChange": 0,
      "oiChangePct": 0,
      "volumeOiRatio": 0,
      "bidVolume": 0,
      "askVolume": 0,
      "bidPct": 0,
      "askPct": 0,
      "lastPrice": 0,
      "underlyingPrice": 0,
      "iv": 0,
      "moneynessPct": 0,
      "sweepVolume": 0,
      "sweepPremium": 0,
      "multiLegVolume": 0,
      "multiLegPremium": 0
    }
  ],
  "meta": {
    "timestamp": "string",
    "requestId": "d7574836"
  }
}
```

### 400

Request validation failed.

invalidParam:

```json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid parameter 'timeframe': must be one of [1m, 5m, 15m, 1h, 4h, 1d, 1w, 1M]"
  }
}
```

### 401

Missing or invalid API key.

missingKey:

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
```

### 402

The account's shared Skylit credit balance is lower than this route's cost. Top up to continue. Carries `X-Credits-Remaining: 0`.

Headers: `X-Credits-Remaining`.

outOfCredits:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Out of credits. Top up to continue making requests."
  }
}
```

### 429

Per-minute rate limit exceeded.

Headers: `Retry-After`.

tooFast:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit of 100 req/min exceeded. Retry after 18s."
  }
}
```