---
title: "Expiry (DTE) concentration"
method: GET
path: "/options-flow/expiry"
tags: ["Derived Analytics"]
---

# Expiry (DTE) concentration

`GET /options-flow/expiry`

## Request

- Base URL: `https://optionsbell.com/api/v1`
- URL: `https://optionsbell.com/api/v1/options-flow/expiry`
- Auth: API key in header `X-API-Key`

Where the day's unusual premium sits along the DTE axis, in fixed
buckets with call/put splits. Buckets on `days_to_expiration`, the
calendar-day count from `data_date` to `expiration_date` computed by
the API: `0-7` (dte <= 7), `8-30`, `31-90`, `90+`
(dte > 90); rows without a DTE are excluded. Buckets are ordered
short-dated first; a bucket with no contracts is omitted. `date` in
the response is the day that was aggregated, also when the latest-day
default was used.

## Query parameters

- `date` string, date
- `symbols` string

## Response `200`

DTE buckets

- object
  - `date` string, date, nullable, required
  - `symbols` string[], nullable, required: Echo of the parsed symbols filter; null when not sent.
  - `count` integer, required: Number of buckets returned
  - `buckets` ExpiryBucket[], required
    - `dte_bucket` '0-7' | '8-30' | '31-90' | '90+'
    - `contracts` integer
    - `volume` string: Numeric string.
    - `premium_estimate` string: Numeric string. USD.
    - `call_contracts` integer
    - `put_contracts` integer
    - `call_premium` string: Numeric string. USD.
    - `put_premium` string: Numeric string. USD.

## Other responses

- `400`: Invalid input: `INVALID_DATE`, `INVALID_SYMBOLS`.
- `401`: Missing or invalid API key: `MISSING_API_KEY`, `INVALID_API_KEY_FORMAT`, `INVALID_API_KEY`. No rate-limit headers.
- `403`: Key is valid but has no usable subscription: `NO_ACTIVE_SUBSCRIPTION` (no Personal plan on the key) or `SUBSCRIPTION_INACTIVE` (past due, paused, expired, or canceled past its period end). No rate-limit headers.
- `429`: Rate limit exceeded: `RATE_LIMIT_MINUTE` (60/min) or `RATE_LIMIT_DAY` (4,000/day). Carries both rate-limit header sets and `Retry-After` (seconds until the exhausted window opens again). Rejected requests count against the minute window, so back off instead of retrying immediately.
- `500`: Unexpected server error: `INTERNAL_ERROR`. The body and the X-Request-Id header carry the request id.
- `503`: Authentication backend unreachable: `AUTH_UNAVAILABLE`. Retry later. No rate-limit headers.

---

[API](https://skmtc.dev/optionsbell/apis/optionsbell-options-flow-api.md) · [All operations](https://skmtc.dev/optionsbell/apis/optionsbell-options-flow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/optionsbell/apis/optionsbell-options-flow-api/revisions/42db9bcaa61f?raw)