v1

latestOpenAPI 3.1.0MIT2026-08-0453113564.4 KB

X/Twitter Stocks

Market Sentiment

Returns the service-level X/Twitter market sentiment snapshot across all tracked stocks when you want a single X-wide market state instead of per-ticker rankings. It includes service-wide buzz, sentiment split, activity trend, breadth metrics and the top drivers by current buzz_score.

buzz_score here means relative X/Twitter market heat, not pure bullishness. It measures how hot overall X stock discussion is versus X's own trailing 90-day baseline:

around 50 = normal X market activity
higher = more active than usual
lower = quieter than usual

trend is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For from/to, anchors at to (or now when to is today).

Use sentiment_score, bullish_pct and bearish_pct for direction.

get/x/stocks/v1/market-sentiment

Query parameters

fromstring date nullable

Start date in YYYY-MM-DD. Inclusive UTC date.

tostring date nullable

End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.

daysinteger

Deprecated v1 compatibility shorthand. Prefer from and to for reproducible UTC date windows.

Response

Successful Response

buzz_scorenumber nullable required

Service-wide X/Twitter heat score relative to the service's trailing 90-day baseline. Around 50 = normal activity, higher values = hotter-than-usual X activity.

trend'rising' | 'falling' | 'stable' nullable

Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For from/to, anchors at to (or now when to is today).

mentionsinteger required

Tweet mentions across the selected period

unique_tweetsinteger required

Exact distinct tweet count across the selected UTC period

unique_authorsinteger required

Exact distinct author breadth across the selected UTC period

total_upvotesinteger required

Total likes across the selected period

active_tickersinteger required

Number of tickers with X activity in the selected period

sentiment_scorenumber nullable

Service-wide average tweet sentiment score

positive_countinteger required

Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility.

negative_countinteger required

Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility.

neutral_countinteger required

Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility.

bullish_pctinteger required

Bullish tweet percentage

bearish_pctinteger required

Bearish tweet percentage

trend_historynumber[]

Daily service-wide buzz scores (oldest→newest) using the same relative baseline calibration. Length = max(requested_days, 7) for successful requests; windows before platform availability return HTTP 422.

Example response

{
  "buzz_score": 56.2,
  "trend": "rising",
  "mentions": 2847,
  "unique_tweets": 913,
  "unique_authors": 604,
  "total_upvotes": 28471,
  "active_tickers": 442,
  "sentiment_score": 0.081,
  "positive_count": 1198,
  "negative_count": 741,
  "neutral_count": 908,
  "bullish_pct": 42,
  "bearish_pct": 26,
  "trend_history": [
    48.9,
    50.7,
    52.6,
    54.4,
    57.1,
    58.3,
    56.2
  ],
  "drivers": [
    {
      "ticker": "TSLA",
      "mentions": 156,
      "buzz_score": 72.5,
      "sentiment_score": 0.35
    },
    {
      "ticker": "NVDA",
      "mentions": 141,
      "buzz_score": 70.8,
      "sentiment_score": 0.27
    }
  ]
}