> ## 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.

# Ticker Sentiment

> A live 0-100 sentiment composite for a ticker: seven components scored vs the ticker's own year, grouped trend / flow / positioning.

Get a live 0-100 sentiment score for a ticker, composed of seven components grouped into
trend, flow, and positioning sub-scores.
Each component is scored as a percentile vs the ticker’s own trailing year and oriented
so 100 is the greed side.
The result carries the composite score with a band label (extreme fear to extreme greed;
cutoffs versioned in the methodology block), the three sub-scores, every component with
its raw value, percentile, and window, deltas over 1, 5, and 20 trading days, a weekly
history series, transition flags, and quotable derived\[] sentences.
A thin option chain degrades to a disclosed coverage with omission reasons, so the score
never silently changes meaning.
Serves live data only.

**Endpoint:** `POST /api/v1/ticker-sentiment`

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

## Request

| Field        | Type     |
| ------------ | -------- |
| `ticker`     | `string` |
| `as_of_date` | `string` |

## Response

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

| Field          | Description                                                                                                                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ticker`       | The stock ticker symbol, uppercased (e.g. "AAPL").                                                                                                                                                                                              |
| `as_of_date`   | The calendar date the score reflects, in YYYY-MM-DD format.                                                                                                                                                                                     |
| `price`        | The underlying price at the snapshot, or null when unavailable.                                                                                                                                                                                 |
| `score`        | The composite sentiment score, 0-100 (100 = greed-side), as the equal-weight mean of the scored components. Null when no component cleared its data gates.                                                                                      |
| `band`         | The band label for the score: "extreme fear", "fear", "neutral", "greed", or "extreme greed" (cutoffs versioned in methodology). Null when the score is null.                                                                                   |
| `coverage`     | How many components were scored, as "N/7" over the v1 component set.                                                                                                                                                                            |
| `sub_scores`   | The mean score within each group (trend, flow, and positioning), each null when no component in that group was scored.                                                                                                                          |
| `components`   | The scored components, each with: id, group, raw (today's value), unit, percentile (0-100 vs the ticker's own window), score (oriented so 100 = greed-side), the reference window, and an optional note when an interim source was substituted. |
| `omitted`      | Components dropped from the composite, each with the component id and the reason (history\_accumulating, thin\_chain, insufficient\_history, or no\_data), so a degraded score is always explained.                                             |
| `delta`        | Change in the composite over 1, 5, and 20 trading days (d1/d5/d20), each computed on today's component set so the comparison is like-for-like. Null when the prior anchor was not computable.                                                   |
| `history`      | Weekly composite closes (oldest first), each with its date, score, and coverage at that point.                                                                                                                                                  |
| `flags`        | Notable transitions on this snapshot (e.g. entered\_extreme\_fear, crossed\_below\_125d\_ma, flow\_positioning\_divergence).                                                                                                                    |
| `context`      | Event context: next\_earnings carries the upcoming earnings date, days until it, and whether it is confirmed (null when no upcoming date is known).                                                                                             |
| `derived`      | Quotable plain-English sentences summarizing the score, its drivers, and any caveats. The first sentence doubles as a headline.                                                                                                                 |
| `scope`        | What the options-derived components saw: selection (full\_chain or partial\_chain when the fetch cap stopped at a prefix), contracts\_analyzed, expirations\_covered, and pages\_fetched.                                                       |
| `data_quality` | Reading reliability: status ("ok", "degraded" when components were omitted, or "no\_data"), history (status and days\_collected for the trailing daily series), and an optional note.                                                           |
| `methodology`  | A versioned description of the scoring: component\_scoring, composite, band\_cutoffs (the four ascending thresholds between the five band labels), orientation, and flow\_sharing.                                                              |

## Example

```bash theme={"system"}
finterm tool ticker_sentiment AAPL
```