# Cluster rotation

- Method: `GET`
- Path: `/clusters/rotation`
- Credits: 2
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-clusters-rotation/
- Interactive docs: https://docs.hiddensystems.ai/nebula/api/#endpoint=get-clusters-rotation

## Description

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`.

## cURL Example

```bash
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'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `cluster_id` (string, 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.
- `asset_class` (array<string>, optional, default: equity,commodity,index,crypto, allowed: equity, commodity, index, crypto, comma-separated): 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.
- `hours` (integer, optional, default: 168, allowed: 24, 168, 720, range: 24–720): 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.
- `limit` (integer, optional, default: 6, range: 1–20): Maximum gainers returned, and separately maximum losers.

## Response

OK

- `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, enum: equity, commodity, index, crypto): The asset's class: equity (stocks and ETFs), commodity, index, or crypto. Send it with asset_id on every asset-scoped request.
- `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, enum: equity, commodity, index, crypto): The asset's class: equity (stocks and ETFs), commodity, index, or crypto. Send it with asset_id on every asset-scoped request.
- `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, enum: equity, commodity, index, crypto, people, events): equity, commodity, index, crypto, people (people and their accounts) or events (places, themes and events).
- `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, enum: equity, commodity, index, crypto, people, events): equity, commodity, index, crypto, people (people and their accounts) or events (places, themes and events).
- `topic_series[].topics[].topic_share` (number (double), required): The topic's share of the cluster's posts that day, from 0 to 1.

Media type: `application/json`

## JSON Response

```json
{
  "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
        }
      ]
    }
  ]
}
```