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

Emotion distribution

GET /emotions
GetEmotions

Returns post counts and within-bucket proportions for each detected emotion for exactly one resolved asset or non-asset subject. Asset selectors support equities, commodities, indices, and crypto assets returned by GET /assets; commodity and index IDs use asset_class=equity. Parameter rules: One of asset_id or subject_id is required. asset_id requires asset_class. subject_id and asset_class cannot be combined. subject_id and asset_id cannot be combined.

Parameters

asset_id string QUERY

Canonical identifier returned by /assets. Stock, commodity, and index IDs are normally ticker or market symbols and use asset_class=equity; crypto IDs are canonical crypto slugs. asset_class is mandatory whenever asset_id is present.

Example:NVDA

asset_class string QUERY

Namespace of asset_id, or the market class for endpoints with a class-scoped global view. Stocks, commodities, and indices use equity. Equity is the documented default only where the endpoint description states a default.

Allowed values
equitycrypto

Example:equity

subject_id string QUERY

Canonical non-asset identifier returned by /subjects. It cannot be combined with asset_id or asset_class.

Example:person:donald_trump

hours integer QUERY

Lookback window in hours.

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/emotions' \
  --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 Credit balance exhausted
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable

Media type application/json

metadata
object optional

Methodology and request-window metadata needed to interpret the response.
metadata.empty_bucket_policy
string required

How clients should interpret buckets omitted or emitted without data.

metadata.empty_buckets
integer required

Number of buckets with no qualifying data.

metadata.granularity
string required

Time bucket size used by the returned series.

metadata.hours
integer required

Lookback window represented by the response, in hours.

metadata.latest_empty_bucket
string (date-time) optional

Most recent UTC bucket with no qualifying data.

series
object required

Emotion observations keyed by the detected emotion label.

Allowed keys
angeranticipationboredomconfidencedisgustdistrustfeargreedjoyloveoptimismpessimismsadnesssurprisetrust
series.{key}[].post_count
integer (int64) required

Raw number of posts carrying this emotion in the bucket.

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

Share of classified posts carrying this emotion in the bucket, from 0 to 1.

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

UTC RFC 3339 timestamp for the observation or bucket start.

{
  "series": {
    "optimism": [
      {
        "post_count": 286,
        "proportion": 0.37,
        "timestamp": "2026-08-07T15:00:00Z"
      }
    ]
  }
}