Stock Sentiment

Overview

Live X (Twitter) sentiment for any US ticker, using only posts from the preceding 72 hours. The X search itself is bounded to that window, so a quiet ticker is not answered with years-old popular posts that would then be discarded. Active tickers read a second page of results (about 40 posts instead of 20); quiet tickers are not charged for it. A window with no qualifying posts returns `sampleSize: 0` with confidence 0 and the `no_posts_in_window` caveat, and is not recorded in history as a neutral reading. Invalid timestamps, posts more than one minute in the future and older posts are rejected before AI work and counted separately in `sampleDiagnostics`. Each accepted tweet is read by our sentiment model (`sentimentModel` states its version) and scored bullish/bearish/neutral; the response is an engagement-weighted summary plus the tweets behind it. Only posts that actually mention the ticker drive the score — posts X flags as merely related are returned separately in `relatedTweets` and don't count. Exact duplicates are removed, as are templated copies that only vary links, @mentions, numbers or emoji (posts of 25+ normalized characters), and one author contributes at most three direct posts, so repeated posting cannot masquerade as broad agreement; every removal is disclosed in `sampleDiagnostics`. Posts where the cashtag names a same-symbol crypto token rather than the company — stablecoin trading pairs such as `$PEP/USDT`, token quantities being handed out, `$X token` next to on-chain context, or crypto-exchange listings — are excluded and counted in `sampleDiagnostics.cryptoTokenPostsRemoved`; RT-and-follow giveaways and recruitment scams (“if you hold the following stocks, follow him — he turned $2,000 into $500,000”, WhatsApp “shareholders and active traders” groups) are removed as promotional spam and counted in `promoSpamRemoved`. Those diagnostics also measure author diversity and concentration across the complete scored sample, not only the displayed top posts. `analysis` measures AI coverage only across the direct posts that determine the ticker score. `insights` combines those facts with bull/bear disagreement and the stored seven-day trend; its confidence is evidence confidence, not a return forecast. Every returned post carries English text in `textEn`: a translation when the post is not confirmed English — including posts X labels `und`, leaves unlabelled, or labels English while written in another script — and the original text when it already is English, so one field always reads as English. A translation that fails is left empty rather than presenting the original as English, and is reported in `analysis.translations`. Each post also carries its post date (`createdAt`). Cached tickers are additionally refreshed in the background, oldest first, so a symbol nobody requests cannot sit frozen. Failed source or enrichment work shares a one-hour cooldown, disclosed with retry fields, so repeated readers do not multiply X or AI requests. Cached ~30 min per ticker; `fresh=1` respects a five-minute minimum successful refresh interval and a source-failure cooldown: when a forced refresh is deferred the body carries `refreshDeferred: true`, `refreshDeferredReason` (`minimum_refresh_interval` or `source_failure_cooldown`) and `retryAfterSeconds`, and the same seconds travel in the `Retry-After` header, so a client can read why the refresh did not run. Stale fallback is never served once the original snapshot reaches 24 hours. Repeated `ticker` or `fresh` parameters return HTTP 400 rather than silently selecting one value. Without a ticker the response lists every cached ticker; that listing accepts `fields=` (comma-separated subset of the snapshot fields), `limit=` (1-200) and `offset=`: with either pagination parameter the body adds `total`, `offset` and `limit`, and `fields` projects each entry, so a client can read a light page instead of the full multi-megabyte body. Without them the listing is unchanged. A cold ticker the listing source does not recognize returns HTTP 404 before any X search or AI work; if the probe itself cannot answer, the request proceeds exactly as before (the check fails open). The same response is also served at `/api/stock-sentiment` (alias of this path, byte-identical behavior). Field by field, `sampleDiagnostics` accounts for the sample: posts received, dropped as duplicates, malformed, future-dated or stale, removed by the per-author cap (`authorPostCap`, `authorCapRemoved`) or the related-post cap, and the concentration of what survived — `uniqueAuthors`, `dominantAuthor` with its share, and `effectiveAuthorCount`, the number of independent voices the posts really amount to. `insights.evidence` repeats that measurement, separating the evidence visible in the response from the whole scored sample, and `insights.confidence.factors` breaks the confidence score into its parts (sample depth, author diversity, classification coverage, analysis completeness and directional agreement), so a low number says which part is weak; a sample split between bullish and bearish cannot be labelled high confidence however deep it is. `insights.trend7Days` is the stored seven-day trend, not a forecast. The scoring formula this endpoint shares with Market Sentiment — post score, engagement weight, weighted mean and the ±0.15 label thresholds — is written once, in full, under **How the score is computed** on [/docs/market-sentiment](/docs/market-sentiment); that page also states the two factors Market Sentiment applies and this endpoint does not, so the same page answers 'is my score computed like theirs?' instead of two texts that drift apart. In short: here there is no source weighting and no time decay. The 72-hour window is a hard cut, a post from 70 hours ago weighs exactly as much as one from an hour ago, and a loud author is limited by the cap of three direct posts rather than by a weight.

Use it toGauge how traders feel about a specific stock right now, before you act.

The current snapshot does not depend on the optional trend store. If that store is unavailable, the endpoint still returns the snapshot with `insights.trend7Days.direction=insufficient-data`; `insights.confidence.caveats` includes `trend_history_unavailable` so clients can distinguish an outage from a trend that has not accumulated enough observations yet.

Coverage

Call it

Send your ra_live_… key in the x-api-key header. Pick your language:

curl "https://raspberrytrades.com/api/sentiment?ticker=NVDA" \
  -H "x-api-key: ra_live_your_key_here"