# Sentiment

- Method: `GET`
- Path: `/sentiment`
- Tier: Free
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-sentiment/
- Interactive docs: https://docs.hiddensystems.ai/nebula/api/#endpoint=get-sentiment

## Description

Returns Nebula's primary sentiment series for one asset, one non-asset subject, or a market-wide asset class. Free receives the high-level series; named cohort breakdowns and cluster filtering require Pro. Omit identity selectors for the global view; asset_class then defaults to equity. Asset selectors support equities, commodities, indices, and crypto assets returned by GET /assets; commodity and index IDs use asset_class=equity. Parameter rules: asset_id requires asset_class. subject_id and asset_class cannot be combined. subject_id and asset_id cannot be combined.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/sentiment' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `asset_id` (string, optional): 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.
- `asset_class` (string, optional, allowed: equity, crypto): 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.
- `subject_id` (string, optional): Canonical non-asset identifier returned by /subjects. It cannot be combined with asset_id or asset_class.
- `hours` (integer, optional, default: 168): Lookback window in hours.
- `granularity` (string, optional, allowed: 1h, 2h, 4h, 12h, 1d): Requested time-series bucket size. When omitted, the service chooses a bucket size appropriate for the lookback window.
- `clusters` (array<string>, optional): Repeatable canonical author-cluster filter. Use /clusters to discover current cluster IDs.

## Response

OK

- `cohorts` (object, required, allowed keys: bots, non_bots, top_callers): Named sentiment populations. Current keys are bots, non_bots, and top_callers when that population is available.
- `cohorts.{key}[].bearish_posts` (number (double), required): Posts classified as bearish.
- `cohorts.{key}[].bullish_posts` (number (double), required): Posts classified as bullish.
- `cohorts.{key}[].interval_bearish_posts` (number (double)): Bearish posts in this emitted time bucket.
- `cohorts.{key}[].interval_bullish_posts` (number (double)): Bullish posts in this emitted time bucket.
- `cohorts.{key}[].interval_neutral_posts` (number (double)): Neutral posts in this emitted time bucket.
- `cohorts.{key}[].interval_posts` (number (double)): Posts in this emitted time bucket, before lookback accumulation.
- `cohorts.{key}[].neutral_posts` (number (double), required): Posts classified as neutral.
- `cohorts.{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.
- `cohorts.{key}[].sentiment_signal_z_score` (number (double)): Standard score of the sentiment signal when available.
- `cohorts.{key}[].smoothed_sentiment_signal` (number (double)): Smoothed form of the sentiment signal when available.
- `cohorts.{key}[].smoothed_total_posts` (number (double)): Smoothed form of total post activity when available.
- `cohorts.{key}[].timestamp` (string (date-time), required): UTC RFC 3339 timestamp for the observation or bucket start.
- `cohorts.{key}[].total_posts` (number (double), required): Post count over the metric's active lookback window.
- `series` (array<object>, required): Chronologically ordered observations.
- `series[].bearish_posts` (number (double), required): Posts classified as bearish.
- `series[].bullish_posts` (number (double), required): Posts classified as bullish.
- `series[].interval_bearish_posts` (number (double)): Bearish posts in this emitted time bucket.
- `series[].interval_bullish_posts` (number (double)): Bullish posts in this emitted time bucket.
- `series[].interval_neutral_posts` (number (double)): Neutral posts in this emitted time bucket.
- `series[].interval_posts` (number (double)): Posts in this emitted time bucket, before lookback accumulation.
- `series[].neutral_posts` (number (double), required): Posts classified as neutral.
- `series[].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[].sentiment_signal_z_score` (number (double)): Standard score of the sentiment signal when available.
- `series[].smoothed_sentiment_signal` (number (double)): Smoothed form of the sentiment signal when available.
- `series[].smoothed_total_posts` (number (double)): Smoothed form of total post activity when available.
- `series[].timestamp` (string (date-time), required): UTC RFC 3339 timestamp for the observation or bucket start.
- `series[].total_posts` (number (double), required): Post count over the metric's active lookback window.

Media type: `application/json`

## JSON Response

```json
{
  "cohorts": {
    "non_bots": [
      {
        "bearish_posts": 438,
        "bullish_posts": 1120,
        "neutral_posts": 284,
        "sentiment_signal": 128.6,
        "timestamp": "2026-08-07T15:00:00Z",
        "total_posts": 1842
      }
    ]
  },
  "series": [
    {
      "bearish_posts": 438,
      "bullish_posts": 1120,
      "interval_bearish_posts": 18,
      "interval_bullish_posts": 46,
      "interval_neutral_posts": 10,
      "interval_posts": 74,
      "neutral_posts": 284,
      "sentiment_signal": 128.6,
      "sentiment_signal_z_score": 1.42,
      "smoothed_sentiment_signal": 117.3,
      "smoothed_total_posts": 1765.4,
      "timestamp": "2026-08-07T15:00:00Z",
      "total_posts": 1842
    }
  ]
}
```