---
title: "Market breadth and regime"
method: GET
path: "/options-flow/market"
tags: ["Derived Analytics"]
---

# Market breadth and regime

`GET /options-flow/market`

## Request

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

Breadth of unusual flow per trading day, newest first: `breadth_score`
0-100 (share of classified symbols reading bullish; null only when no
symbol was classified that day), aggregate call/put volume ratio,
regime label (`bullish` / `bearish` / `mixed`) and bullish/bearish
symbol counts. Without `date` / range the envelope's `date` is the
latest available day and `data` holds the newest `limit` days.

## Query parameters

- `date` string, date
- `date_from` string, date
- `date_to` string, date
- `limit` integer

## Response `200`

Daily market rows

- object
  - `date` string, date, nullable, required
  - `date_from` string, date, nullable, required
  - `date_to` string, date, nullable, required
  - `count` integer, required
  - `data` MarketRow[], required
    - `date` string, date
    - `breadth_score` integer, nullable: Share of classified symbols reading bullish; null only when none were classified.
    - `call_put_ratio` number, nullable: Aggregate call vs. put volume across flagged names.
    - `regime` 'bullish' | 'bearish' | 'mixed'
    - `bullish_count` integer
    - `bearish_count` integer

## Other responses

- `400`: Invalid input: `INVALID_DATE`, `INVALID_DATE_RANGE`, `INVALID_PARAM`.
- `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)