> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finterm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Options Sentiment

> Put/call options sentiment for a symbol on a specific date, with a sample-quality verdict.

Measure options-market sentiment for one underlying symbol on a specific date.
Returns the put/call volume ratio and its fixed convention label (below 0.7 bullish,
0.7–1.0 neutral, above 1.0 bearish), call and put volume, the average bid/ask spread,
and a liquidity grade.
The thresholds are descriptive conventions, not calibrated forecasts for a symbol or
market regime. A data\_quality block reports whether the sample is solid ("ok"), empty
("no\_data", e.g. a non-trading day), or too small to trust ("thin\_sample"), so a reading
is never mistaken for a confident one.
The date is required and identifies which day to report.

**Endpoint:** `POST /api/v1/options/sentiment`

**Tier:** point · **Delivery:** sync

## Request

| Field                     | Type      |
| ------------------------- | --------- |
| `underlying_ticker`       | `string`  |
| `date`                    | `string`  |
| `include_spread_analysis` | `boolean` |
| `expiration_filter`       | `string`  |
| `max_contracts`           | `number`  |

## Response

The response is the two-key envelope `{ finterm, data }`, where `data` is the `finterm.result:OptionsSentiment/v1` contract:

| Field          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ticker`       | The underlying stock ticker symbol, uppercased (e.g. "AAPL").                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `as_of_date`   | The date the sentiment is reported for, in YYYY-MM-DD format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `sentiment`    | Put/call sentiment for the day: put\_call\_volume\_ratio (put volume ÷ call volume; the fixed convention labels below 0.7 bullish, 0.7–1.0 neutral, and above 1.0 bearish), the interpretation label, total\_call\_volume, total\_put\_volume, avg\_spread\_percent (average bid/ask spread as a percent of midpoint), and liquidity\_grade (A best to D worst). Ratio, interpretation, spread, and grade are null when there is no volume to read or spread analysis was not requested. The thresholds are descriptive conventions, not calibrated forecasts for a symbol or market regime. |
| `data_quality` | Sample-quality verdict: status ("ok", "no\_data" for a day with no traded contracts, or "thin\_sample" for a low-volume sample), contracts\_analyzed, contracts\_with\_volume, and total\_volume. Use it to weight or discard the reading.                                                                                                                                                                                                                                                                                                                                                   |
| `contracts`    | Contract-count summary for the analyzed sample: total\_calls, total\_puts, contracts\_with\_volume, and the list of expirations covered (YYYY-MM-DD).                                                                                                                                                                                                                                                                                                                                                                                                                                        |

## Example

```bash theme={"system"}
finterm tool options_sentiment AAPL --as-of-date 2024-01-15
```