All docs Nebula docs All endpoints Interactive docs Markdown OpenAPI JSON
  1. REST API
  2. Social & Sentiment

Sentiment by timeframe

GET /sentiment/timeframes
GetSentimentTimeframes

Sentiment split by the horizon people are talking about: short term (up to a week), medium term (weeks to months), and long term (three months or more), each on the /sentiment scale. Separates a crowd that is bearish this week but bullish on the year from one that is bearish throughout.

Parameter rules:

  • Send asset_id or subject_id.
  • asset_id must be sent with asset_class.
  • subject_id cannot be combined with asset_id or asset_class.

Wallet payment available at https://nebula-api.hiddensystems.ai/api/v1/x402/sentiment/timeframes. No Nebula account or API key required; check the payment offer before signing. x402 payment guide.

Parameters

asset_id string QUERY

Asset ID from /assets or /search, such as NVDA, GLD, SPX, or bitcoin. Send it with the asset_class returned alongside it.

Example:NVDA

asset_class string QUERY

Class of the asset named by asset_id: equity (stocks and ETFs), commodity, index, or crypto. Send the asset_class that /assets or /search returned alongside the asset_id.

Allowed values
equitycommodityindexcrypto

Example:equity

subject_id string QUERY

Canonical non-asset identifier returned by /subjects or /search, such as text:jensen huang or handle:elonmusk. Accepted in any case. It cannot be combined with asset_id or asset_class.

Example:text:jensen huang

hours integer QUERY

Lookback window in hours. Free plans reach back 90 days; further returns 403.

Default:720

granularity string QUERY

Requested time-series bucket size. When omitted, the service chooses a bucket size appropriate for the lookback window.

Allowed values
1h2h4h12h1d

Example:1h

cURL Example

curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/sentiment/timeframes' \
  --data-urlencode 'asset_id=NVDA' \
  --data-urlencode 'asset_class=equity' \
  --header 'X-API-Key: YOUR_API_KEY'

Responses

200 OK
400 Bad Request
401 Unauthorized
402 Credits used up; response includes renewal timing and purchased credit balance
403 Forbidden
404 Not Found
405 Method not allowed; the Allow header lists the supported method
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable

Media type application/json

current
object required

Latest sentiment reading for each available timeframe horizon.

Allowed keys
short_termmedium_termlong_term
metadata
object optional

Methodology and request-window metadata needed to interpret the response.
metadata.as_of
string (date-time) optional

UTC time at which the metric was calculated.

metadata.calculation
string optional

Short name for the calculation method.

metadata.formula
string optional

Human-readable formula for the calculation.

metadata.half_life_hours
number (double) optional

Despite the name, the length of the linear decay window, in hours: a post counts fully when new, half at the midpoint, and not at all once it is this old.

metadata.lookback_days
integer optional

Historical lookback used by the calculation, in days.

metadata.scale
string optional

Published scale or interpretation of the metric.

series
object required

Sentiment series keyed by short_term, medium_term, and long_term horizon.

Allowed keys
short_termmedium_termlong_term
series.{key}[].interval_posts
number (double) optional

Posts in this emitted time bucket, before lookback accumulation.

series.{key}[].sentiment_signal
number (double) required

Decay-weighted net bullish posts: bullish minus bearish. Positive is bullish, negative is bearish, and magnitude grows with activity.

series.{key}[].timestamp
string (date-time) required

UTC RFC 3339 timestamp for the observation or bucket start.

series.{key}[].total_posts
number (double) optional

Post count over the metric's active lookback window.

{
  "current": {
    "long_term": 52.1,
    "medium_term": 57.8,
    "short_term": 64.2
  },
  "series": {
    "short_term": [
      {
        "sentiment_signal": 64.2,
        "timestamp": "2026-08-07T15:00:00Z",
        "total_posts": 318
      }
    ]
  }
}