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

Cluster rotation

GET /clusters/rotation
GetClusterRotation

Where one cluster's attention is moving.

gainers and losers are the assets whose share of the cluster's posts changed most against the previous window, in basis points (100 is one percentage point); an asset needs 3 or more posts. hours=24 uses hourly data; 168 and 720 use complete UTC days. topic_series and topic_changes split the cluster's posts by day across the selected asset classes, people and events.

Built from a daily per-cluster rollup of complete UTC days (today excluded, refreshed every few hours). The market is every author except bots; asset_class filters the cluster, the market and peers.

Parameter rules:

  • Send cluster_id.
  • cluster_id names one cluster; to compare several, call once per cluster or use /clusters for every cluster at once.
  • Posting communities (wallstreetbets, reddit) cover equities only: with one of them, asset_class must include equity.

Parameters

cluster_id string QUERY required

The author cluster to analyse, as the cluster_id /clusters returns, for example smart_money, kols, macro_analyst, or wallstreetbets. Every id listed under the clusters parameter of /sentiment is accepted, including the caller lists (smart_money, dumb_money, top_degens) and the posting communities (wallstreetbets, reddit). An unknown id returns 400.

Example:smart_money

asset_class array<string> QUERY

The markets to analyse: equity (stocks and ETFs), commodity, index, crypto, or any combination, for example asset_class=equity,index. Defaults to all four. Posting communities cover equities only, so with wallstreetbets or reddit the selection must include equity. Send several comma-separated.

Default:equity,commodity,index,crypto

hours integer QUERY

The window to compare with the window of the same length before it: 24 (the last 24 hours), 168 (the last 7 complete days), or 720 (the last 30 complete days). Free plans read up to 90 days back; Pro plans up to this parameter's maximum. A value reaching past your plan's window returns 403 and is not charged.

Allowed values
24168720

Default:168

limit integer QUERY

Maximum gainers returned, and separately maximum losers.

Default:6

cURL Example

curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/clusters/rotation' \
  --data-urlencode 'cluster_id=smart_money' \
  --header 'X-API-Key: YOUR_API_KEY'

Responses

200 OK
400 Bad Request
401 Unauthorized
402 Credits used up; upgrade_url links to buying more
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

asset_classes
array<string> required

The markets analysed, in the order equity, commodity, index, crypto: the asset_class values requested, or all four when asset_class was omitted.

cluster_id
string required

The cluster analysed, as its canonical cluster_id.

gainers
array<object> required

Assets whose share of the cluster's posts rose most, largest gain first. Only assets whose share rose are listed.
gainers[].asset_class
string required

The asset's class: equity (stocks and ETFs), commodity, index, or crypto. Send it with asset_id on every asset-scoped request.

Allowed values
equitycommodityindexcrypto
gainers[].asset_id
string required

Canonical public asset identifier: the ticker or market symbol for stocks, commodities, and indices, and the CoinGecko slug (or, without one, a numeric id) for crypto.

gainers[].current_share
number (double) required

Posts as a fraction of all the cluster's posts about the selected asset classes in the current window, from 0 to 1.

gainers[].name
string required

Human-readable name.

gainers[].previous_share
number (double) required

The asset's posts as a fraction of all the cluster's posts in the comparison window, from 0 to 1.

gainers[].share_change_bps
integer required

current_share minus the share in the comparison window, in basis points: 100 is one percentage point. Negative means the share fell.

gainers[].symbol
string required

Display ticker or market symbol.

hours
integer required

Lookback window represented by the response, in hours.

losers
array<object> required

Assets whose share of the cluster's posts fell most, largest fall first. Only assets whose share fell are listed.
losers[].asset_class
string required

The asset's class: equity (stocks and ETFs), commodity, index, or crypto. Send it with asset_id on every asset-scoped request.

Allowed values
equitycommodityindexcrypto
losers[].asset_id
string required

Canonical public asset identifier: the ticker or market symbol for stocks, commodities, and indices, and the CoinGecko slug (or, without one, a numeric id) for crypto.

losers[].current_share
number (double) required

Posts as a fraction of all the cluster's posts about the selected asset classes in the current window, from 0 to 1.

losers[].name
string required

Human-readable name.

losers[].previous_share
number (double) required

The asset's posts as a fraction of all the cluster's posts in the comparison window, from 0 to 1.

losers[].share_change_bps
integer required

current_share minus the share in the comparison window, in basis points: 100 is one percentage point. Negative means the share fell.

losers[].symbol
string required

Display ticker or market symbol.

topic_changes
array<object> required

Each topic's share of the current window and its change against the previous one, in the order equity, commodity, index, crypto, people, events.
topic_changes[].current_share
number (double) required

The topic's share of the cluster's posts in the current window, from 0 to 1.

topic_changes[].share_change_bps
integer required

Change in share against the previous window, in basis points (100 is one percentage point).

topic_changes[].topic
string required

equity, commodity, index, crypto, people (people and their accounts) or events (places, themes and events).

Allowed values
equitycommodityindexcryptopeopleevents
topic_series
array<object> required

Each topic's share of the cluster's posts per complete UTC day, oldest first.
topic_series[].timestamp
string (date-time) required

UTC start of the day: 00:00.

topic_series[].topics
array<object> required

Each topic's share of the cluster's posts that day, in the order of topic_changes. The shares add up to 1 when the cluster posted that day.
topic_series[].topics[].topic
string required

equity, commodity, index, crypto, people (people and their accounts) or events (places, themes and events).

Allowed values
equitycommodityindexcryptopeopleevents
topic_series[].topics[].topic_share
number (double) required

The topic's share of the cluster's posts that day, from 0 to 1.

{
  "asset_classes": [
    "equity",
    "commodity",
    "index",
    "crypto"
  ],
  "cluster_id": "smart_money",
  "gainers": [
    {
      "asset_class": "equity",
      "asset_id": "NVDA",
      "current_share": 0.0687,
      "name": "NVIDIA Corporation",
      "previous_share": 0.0412,
      "share_change_bps": 275,
      "symbol": "NVDA"
    }
  ],
  "hours": 168,
  "losers": [
    {
      "asset_class": "equity",
      "asset_id": "TSLA",
      "current_share": 0.0318,
      "name": "Tesla, Inc.",
      "previous_share": 0.0521,
      "share_change_bps": -203,
      "symbol": "TSLA"
    }
  ],
  "topic_changes": [
    {
      "current_share": 0.52,
      "share_change_bps": 120,
      "topic": "equity"
    },
    {
      "current_share": 0.03,
      "share_change_bps": -15,
      "topic": "commodity"
    },
    {
      "current_share": 0.04,
      "share_change_bps": 10,
      "topic": "index"
    },
    {
      "current_share": 0.14,
      "share_change_bps": -115,
      "topic": "crypto"
    },
    {
      "current_share": 0.11,
      "share_change_bps": 35,
      "topic": "people"
    },
    {
      "current_share": 0.16,
      "share_change_bps": -35,
      "topic": "events"
    }
  ],
  "topic_series": [
    {
      "timestamp": "2026-09-10T00:00:00Z",
      "topics": [
        {
          "topic": "equity",
          "topic_share": 0.5
        },
        {
          "topic": "commodity",
          "topic_share": 0.03
        },
        {
          "topic": "index",
          "topic_share": 0.04
        },
        {
          "topic": "crypto",
          "topic_share": 0.15
        },
        {
          "topic": "people",
          "topic_share": 0.11
        },
        {
          "topic": "events",
          "topic_share": 0.17
        }
      ]
    },
    {
      "timestamp": "2026-09-11T00:00:00Z",
      "topics": [
        {
          "topic": "equity",
          "topic_share": 0.53
        },
        {
          "topic": "commodity",
          "topic_share": 0.03
        },
        {
          "topic": "index",
          "topic_share": 0.04
        },
        {
          "topic": "crypto",
          "topic_share": 0.13
        },
        {
          "topic": "people",
          "topic_share": 0.11
        },
        {
          "topic": "events",
          "topic_share": 0.16
        }
      ]
    }
  ]
}