# Relative-volume bars for a contract

`GET https://flow-api.skylit.ai/v1/contract/{symbol}/rvol`

API: Flowseeker. Credits: 1.

Same shape as `/v1/underlying/{ticker}/rvol` but scoped to a
single contract.

## Authentication

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | path | string | yes | OPRA option symbol in URL-safe form: `{ticker}__{YYMMDD}{C\|P}{strike×1000, 8 digits}` — the ticker and the 15-character contract block are joined by a **double underscore** (`__`). For example, an AAPL $250 call expiring 2026-01-17 is `AAPL__260117C00250000`. (A space-padded 21-char OCC form such as `AAPL 260117C00250000` is also accepted on some endpoints, but the `__` form is canonical and works across all contract routes.) |
| `interval` | query | string | no | Trailing window — `{N}D` where N is 1–365. (default `1D`) |
| `bucket` | query | string | no |  (one of `1min`, `5min`, `10min`, `15min`, `30min`, `1d`, `1w`; default `5min`) |
| `avg_period` | query | string | no | Baseline lookback as `{N}d` (e.g. `14d`). Max 365 days. (default `14d`) |
| `date` | query | string (date) | no | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). |
| `order_by` | query | string | no |  (one of `rvol`, `volume`, `premium`, `time`; default `time`) |
| `order` | query | string | no | Sort direction. Defaults to `asc` when `order_by=time`, otherwise `desc`. (one of `asc`, `desc`) |
| `limit` | query | integer | no |  (min 1) |
| `format` | query | string | no |  (one of `full`, `summary`; default `full`) |

## Example request

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

## Responses

### 200

RVOL bars + aggregate stats for the contract.

Shape (placeholder values):

```json
{
  "data": {
    "bars": [
      {
        "timestamp": "string",
        "timestampEnd": "string",
        "volume": 0,
        "premium": 0,
        "avgVolume": 0,
        "avgPremium": 0,
        "avgDaysCount": 0
      }
    ],
    "stats": {
      "todayVolume": 0,
      "todayPremium": 0,
      "avgVolume": 0,
      "avgPremium": 0,
      "rvolVolume": 0,
      "rvolPremium": 0,
      "avgDaysCount": 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."
  }
}
```