Market Mood API

Overview

Market Mood is SentiSense's proprietary 0-100 composite that blends six sub-signals (social sentiment, market direction, risk appetite, social momentum, S&P 500 trend, options flow) into a single fear-or-greed score plus a phase label. The endpoint returns the latest score, the daily history, the per-signal breakdown, and per-sector aggregations so you can compare a sector's mood against the broader market.

Two companion rollups on this page describe the same market from the news-and-social tone side rather than the composite-score side: /api/v1/sentiment/sectors ranks the 11 GICS sectors against the market's own tone, and /api/v1/sentiment/breadth gives the daily bullish/neutral/bearish split of the covered stock universe. All three are precomputed daily snapshots on the same pipeline cadence.

Use cases:

• Build a top-of-page fear/greed gauge for your own dashboard
• Track regime changes (Greed -> Neutral -> Fear) on a 6-month rolling window
• Compare sector-level moods to spot rotation (e.g. Technology in Greed while Energy in Fear)
• Plot any of the six sub-signals on its own time series
• Render a sector heatmap colored by tone relative to the market, not by absolute tone
• Chart sentiment breadth as the tone analogue of an advance/decline line

Versioning: this page spans two API versions. Market Mood lives at /api/v2/market-mood (v2, not the /api/v1/... prefix used by most other endpoints); the two sentiment rollups live under /api/v1/sentiment/.

Access: send your API key on every call. All three endpoints are available on every tier (no PRO gating). Requests count against your monthly quota and per-minute rate limit.

---

GET /api/v2/market-mood

Returns the current Market Mood composite, the daily history over the requested window, the per-signal breakdown, and per-sector summaries.

Parameters:

Parameter	Type	Required	Default	Description
days	int	No	180	Days of history to return

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/market-mood?days=90"

from sentisense import SentiSenseClient

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
result = client.get_market_mood(days=90)
print(f"Score: {result['market']['currentScore']} ({result['market']['phase']})")
print(f"Weekly change: {result['market']['weeklyChange']}")
for signal in result["market"]["signals"]:
    print(f"  {signal['label']}: {signal['value']} (week change: {signal['change']})")

Response Schema:

Field	Type	Description
market.currentScore	double	Latest composite score, 0-100 (null if no data)
market.phase	string	Plain-text phase label derived from the score. One of seven bands: "Extreme Fear" (0-15), "Fear" (16-30), "Anxiety" (31-45), "Neutral" (46-55), "Optimism" (56-70), "Greed" (71-85), "Extreme Greed" (86-100); "---" when the score is null
market.weeklyChange	double	Composite score change vs ~7 days ago (null when insufficient history)
market.signals	array	Per-signal breakdown. Up to 6 entries; only signals present in the latest reading are listed, so match on key, not array position
market.history	array	Daily history points
sectors	object	Map of sector name to sector summary (currentScore, phase, weeklyChange)

Signal entry:

Field	Type	Description
key	string	One of social_sentiment, market_direction, fear_gauge, social_momentum, spy_trend, options_flow
label	string	Human-readable label (e.g. "Social Sentiment", "S&P 500 Trend")
value	double	Latest value of this sub-signal, 0-100
change	double	Change vs ~7 days ago (null when insufficient history)

History point:

Field	Type	Description
date	string	New York date in YYYY-MM-DD format
timestamp	long	Epoch milliseconds for the data point
score	double	Composite score for that day
socialSentiment	double	Social sentiment sub-signal value. Null on days the signal had no reading, so guard the sub-signals rather than assuming every history row is fully populated
marketDirection	double	Market direction sub-signal value
fearGauge	double	Risk appetite sub-signal value (inverse-VIX; field name retained for compatibility)
socialMomentum	double	Social momentum sub-signal value
spyTrend	double	S&P 500 trend sub-signal value
optionsFlow	double	Options flow sub-signal value

Sector summary:

Field	Type	Description
currentScore	double	Latest composite score for the sector
phase	string	Plain-text phase label
weeklyChange	double	Score change vs ~7 days ago (null when insufficient history)

Example Response:

{
  "market": {
    "currentScore": 62.4,
    "phase": "Optimism",
    "weeklyChange": 4.2,
    "signals": [
      { "key": "social_sentiment", "label": "Social Sentiment", "value": 58.3, "change": 1.5 },
      { "key": "market_direction", "label": "Market Direction", "value": 70.0, "change": 5.0 },
      { "key": "fear_gauge", "label": "Risk Appetite", "value": 55.0, "change": -2.1 },
      { "key": "social_momentum", "label": "Social Momentum", "value": 60.5, "change": 3.0 },
      { "key": "spy_trend", "label": "S&P 500 Trend", "value": 68.2, "change": 6.0 },
      { "key": "options_flow", "label": "Options Flow", "value": 57.0, "change": 1.2 }
    ],
    "history": [
      { "date": "2026-04-01", "timestamp": 1775016000000, "score": 55.0, "socialSentiment": null, "marketDirection": 60.0, "fearGauge": 55.0, "socialMomentum": 50.0, "spyTrend": 60.0, "optionsFlow": 57.0 }
    ]
  },
  "sectors": {
    "Information Technology": { "currentScore": 70.5, "phase": "Greed", "weeklyChange": 3.2 },
    "Financials":             { "currentScore": 48.0, "phase": "Neutral", "weeklyChange": -1.5 }
  }
}

---

GET /api/v1/sentiment/sectors

Returns the per-sector sentiment rollup behind the /sentiment page: the 11 GICS sectors compared against the overall market's news-and-social tone.

Financial news carries a structural positive skew as a genre, so an absolute sector reading is bullish on most days and separates sectors poorly. The comparable value is consensusVsMarket, the signed gap between a sector's own bullish-versus-bearish mention balance and the market's. A negative value means the sector is running cooler than the market, not that it is bearish.

Parameters: none.

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/sentiment/sectors"

Response Schema:

Field	Type	Description
schemaVersion	string	Snapshot schema version
generatedAt	long	Epoch seconds for when the rollup was computed
asOf	string	New York calendar day the snapshot represents, YYYY-MM-DD
narrative	string	One-line templated summary (most and least bullish sector, plus covered stock count)
marketConsensusRatio	double	The whole covered universe's directional-consensus ratio for the window, bounded (-1, 1). This is the baseline each sector's consensusVsMarket is measured against
sectors	array	One row per GICS sector

Sector row:

Field	Type	Description
sector	string	GICS level-1 display name (e.g. "Information Technology")
meanSentiment	double	Mean sentiment polarity across covered member stocks, [-1, 1]
label	string	Tone label for meanSentiment: "Bullish", "Neutral", or "Bearish"
meanScore	double	Mean SentiSense Score across covered members (conviction-weighted, signed, open-ranged)
scoreLabel	string	Band label for meanScore
consensusRatio	double	The sector's own directional-consensus ratio over summed member bullish and bearish mention counts, bounded (-1, 1)
consensusVsMarket	double	consensusRatio minus marketConsensusRatio. Positive means the sector runs hotter than the market over the same window, negative means cooler
consensusLabel	string	Band label for consensusVsMarket: "Hotter than market", "In line with market", or "Cooler than market"
bullMentions	long	Summed bullish member mentions for the window
bearMentions	long	Summed bearish member mentions for the window
stockCount	integer	Member stocks that had a sentiment reading (confidence cue)
totalMentions	long	Summed mention volume across those stocks (confidence cue)
topStock	object	Most bullish member stock, as a stock reference
bottomStock	object	Most bearish member stock, as a stock reference

Stock reference (topStock, bottomStock):

Field	Type	Description
ticker	string	Member stock ticker
value	double	That stock's sentiment polarity, [-1, 1]

Example Response (one sector shown):

{
  "schemaVersion": "1.0",
  "generatedAt": 1785597251,
  "asOf": "2026-08-01",
  "narrative": "As of 2026-08-01, Information Technology is the most bullish sector and Communication Services the least bullish by conviction-weighted SentiSense Score, across 959 covered US stocks.",
  "marketConsensusRatio": 0.3204,
  "sectors": [
    {
      "sector": "Information Technology",
      "meanSentiment": 0.1735,
      "label": "Bullish",
      "meanScore": 3.4609,
      "scoreLabel": "Neutral",
      "consensusRatio": 0.2861,
      "consensusVsMarket": -0.0343,
      "consensusLabel": "In line with market",
      "bullMentions": 6117,
      "bearMentions": 3395,
      "stockCount": 163,
      "totalMentions": 882,
      "topStock": { "ticker": "AMBA", "value": 0.8235 },
      "bottomStock": { "ticker": "KN", "value": -0.3 }
    }
  ]
}

---

GET /api/v1/sentiment/breadth

Returns market-wide sentiment breadth: the daily share of the covered US stock universe leaning bullish, neutral, or bearish. It is the tone analogue of an advance/decline line, where each covered stock casts one vote by its mean sentiment.

Each bucket carries the same classification under two weightings. The stock-weighted fields (bullish/neutral/bearish and their *Pct) give one vote per stock; the mention-weighted fields (*MentionPct) weight those votes by each stock's mention volume. When the two disagree, a small number of heavily covered names is carrying the tone.

Parameters: none.

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/sentiment/breadth"

Response Schema:

Field	Type	Description
schemaVersion	string	Snapshot schema version
generatedAt	long	Epoch seconds for when the rollup was computed
asOf	string	New York calendar day the snapshot represents, YYYY-MM-DD
minMentions	integer	Minimum mention volume for a stock to count toward breadth (confidence floor)
latest	object	Today's bucket, repeating the newest entry in series
series	array	Backfilled daily history, oldest to newest, for a distribution chart

Bucket (latest and each series entry):

Field	Type	Description
date	string	New York calendar day for this bucket, YYYY-MM-DD
coveredStocks	integer	Stocks with a reading that cleared minMentions. This is the breadth denominator
totalMentions	long	Summed mention volume across those stocks
bullish	integer	Covered stocks classified bullish
neutral	integer	Covered stocks classified neutral
bearish	integer	Covered stocks classified bearish
bullishPct	double	Bullish share of covered stocks, percent [0, 100]
neutralPct	double	Neutral share of covered stocks, percent
bearishPct	double	Bearish share of covered stocks, percent
netBreadth	double	bullishPct minus bearishPct, in percentage points [-100, 100]
bullishMentionPct	double	Bullish share of mentions rather than of stocks, percent
neutralMentionPct	double	Neutral share of mentions, percent
bearishMentionPct	double	Bearish share of mentions, percent

Example Response (one history bucket shown):

{
  "schemaVersion": "1.0",
  "generatedAt": 1785597251,
  "asOf": "2026-08-01",
  "minMentions": 5,
  "latest": {
    "date": "2026-08-01",
    "coveredStocks": 266,
    "totalMentions": 3063,
    "bullish": 137,
    "neutral": 64,
    "bearish": 65,
    "bullishPct": 51.5,
    "neutralPct": 24.06,
    "bearishPct": 24.44,
    "netBreadth": 27.06,
    "bullishMentionPct": 55.21,
    "neutralMentionPct": 20.37,
    "bearishMentionPct": 24.42
  },
  "series": [
    {
      "date": "2026-07-02",
      "coveredStocks": 218,
      "totalMentions": 2619,
      "bullish": 102,
      "neutral": 62,
      "bearish": 54,
      "bullishPct": 46.79,
      "neutralPct": 28.44,
      "bearishPct": 24.77,
      "netBreadth": 22.02,
      "bullishMentionPct": 46.54,
      "neutralMentionPct": 28.45,
      "bearishMentionPct": 25.01
    }
  ]
}

Notes

• The phase label (for both the market and each sector) maps from the score across seven bands: Extreme Fear (0-15), Fear (16-30), Anxiety (31-45), Neutral (46-55), Optimism (56-70), Greed (71-85), Extreme Greed (86-100).
• Market Mood is recomputed daily after the U.S. market close. Real-time intraday changes are not reflected; check the history timestamps to see the freshness of the latest point.
• The six sub-signals are documented in the SentiSense methodology pages on the main site.
• Sector keys (e.g. Information Technology, Financials) follow the GICS level-1 sector taxonomy on both /api/v2/market-mood and /api/v1/sentiment/sectors; the exact set on Market Mood is whatever has been computed for the requested window.
• The two sentiment rollups are precomputed daily snapshots written by the same pipeline, on the same cadence as Market Mood. Reading them never recomputes, so generatedAt is the freshness signal. Before the first pipeline run of a new snapshot they return an empty shape (sectors: [], or no latest and an empty series) rather than an error.
• Null fields are omitted from the two sentiment rollups rather than serialized as null, so treat any field in the tables above as optional.
• consensusRatio and consensusVsMarket are tone ratios, not SentiSense Scores. They use their own classifier and must not be read with the Score bands; the two quantities are on different scales.
• For per-stock sentiment time series, use the Metrics API. For the ranked most-bullish and most-bearish stock lists, use the sentiment-leaderboard and sentiment-movers trackers.