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

Emotion distribution

GET /emotions
GetEmotions

Which of 15 emotions dominate the conversation about an asset or subject over time. proportion is each emotion's share of the bucket's emotions (they add up to 1); post_count counts posts showing it. A post can show several.

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/emotions. 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/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 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

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

This emotion's share of all emotion tags 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"
      }
    ]
  }
}