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: the assets gaining and losing share of its posts against the previous window, in basis points, and how its posts split across markets, people, and events.

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.

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

Parameters

cluster_id string QUERY required

The cluster to analyse, as /clusters returns it, for example smart_money or wallstreetbets. Any id from the clusters parameter of /sentiment.

Example:smart_money

asset_class array<string> QUERY

The markets to analyse: any of equity, commodity, index, and crypto, comma-separated. Defaults to all four. 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 reach back 90 days; further returns 403.

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; 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

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
        }
      ]
    }
  ]
}