# Cluster comparison

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

## Description

Every author cluster side by side: its posts and their change, how bullish it is against the market, the asset it turned to more than the market did, and its posts day by day.

Per cluster: posts, bullish and bearish posts, and `activity_change_pct`, the change in posts against the previous window of the same length (null when that window is not wholly inside the data or held no posts). `cluster_bullish_share` is bullish ÷ (bullish + bearish) posts, and `market_bullish_share` is the same for the market the cluster reads over the same days and asset classes, so their difference is the cluster's stance against the market. `trending_asset` is the asset the cluster turned to more than the market did over the last 7 complete days, whatever the window: the rise in its share of the cluster's posts against the 7 days before, less the rise in its share of the market's posts. It needs 3 or more cluster posts in the last 7 days, and is null when the cluster out-gains the market on no asset. `series` is every complete day of the window, days without posts included. Clusters come most posts first.

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 every cluster and the market. Posting communities (`wallstreetbets`, `reddit`) cover equities only, so they are absent unless equity is selected.

## cURL Example

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

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `asset_class` (array<string>, optional, default: equity,commodity,index,crypto, allowed: equity, commodity, index, crypto, comma-separated): The markets to compare the clusters across: equity (stocks and ETFs), commodity, index, crypto, or any combination, for example `asset_class=equity,index`. Defaults to all four. Send several comma-separated.
- `days` (integer, optional, default: 30, allowed: 7, 30, 90, range: 7–90): How many complete UTC days to compare, counting back from the latest complete day: 7, 30, or 90. activity_change_pct compares with the same number of days before. 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.

## 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.
- `clusters` (array<object>, required): Every cluster with posts in the window, most posts first.
- `clusters[].activity_change_pct` (number (double), required): Percent change in posts against the previous window of equal length (76 posts after 84 is -9.52); absent when no comparison is possible.
- `clusters[].bearish_posts` (integer (int64), required): The cluster's bearish posts over the window.
- `clusters[].bullish_posts` (integer (int64), required): The cluster's bullish posts over the window.
- `clusters[].cluster_bullish_share` (number (double), required): The cluster's bullish ÷ (bullish + bearish) posts over the window, from 0 to 1. Null with no bullish or bearish posts.
- `clusters[].cluster_id` (string, required): Canonical author-cluster identifier.
- `clusters[].market_bullish_share` (number (double), required): The same share for the market the cluster reads, over the same days and asset classes (the equity market for a posting community): the baseline cluster_bullish_share compares with. Null with no bullish or bearish posts.
- `clusters[].posts` (integer (int64), required): The cluster's posts over the window.
- `clusters[].series` (array<object>, required): Every complete UTC day of the window, oldest first, days without posts included.
- `clusters[].series[].bearish_posts` (integer (int64), required): The cluster's bearish posts on the day.
- `clusters[].series[].bullish_posts` (integer (int64), required): The cluster's bullish posts on the day.
- `clusters[].series[].posts` (integer (int64), required): The cluster's posts on the day.
- `clusters[].series[].timestamp` (string (date-time), required): UTC start of the day: 00:00.
- `clusters[].trending_asset` (object, required): The asset the cluster turned to more than the market did over the last 7 complete days; null when there is none.
- `clusters[].trending_asset.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.
- `clusters[].trending_asset.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.
- `clusters[].trending_asset.name` (string, required): Human-readable name.
- `clusters[].trending_asset.symbol` (string, required): Display ticker or market symbol.
- `days` (integer, required): Window length in complete UTC days, ending at the latest complete day.

Media type: `application/json`

## JSON Response

```json
{
  "asset_classes": [
    "equity",
    "commodity",
    "index",
    "crypto"
  ],
  "clusters": [
    {
      "activity_change_pct": 7.61,
      "bearish_posts": 13550,
      "bullish_posts": 61240,
      "cluster_bullish_share": 0.8188,
      "cluster_id": "media",
      "market_bullish_share": 0.7812,
      "posts": 173412,
      "series": [
        {
          "bearish_posts": 480,
          "bullish_posts": 2210,
          "posts": 6120,
          "timestamp": "2026-09-11T00:00:00Z"
        },
        {
          "bearish_posts": 512,
          "bullish_posts": 2102,
          "posts": 5874,
          "timestamp": "2026-09-12T00:00:00Z"
        }
      ],
      "trending_asset": {
        "asset_class": "equity",
        "asset_id": "NVDA",
        "name": "NVIDIA Corporation",
        "symbol": "NVDA"
      }
    },
    {
      "activity_change_pct": 171.42,
      "bearish_posts": 18860,
      "bullish_posts": 20480,
      "cluster_bullish_share": 0.5206,
      "cluster_id": "wallstreetbets",
      "market_bullish_share": 0.7035,
      "posts": 88034,
      "series": [
        {
          "bearish_posts": 702,
          "bullish_posts": 790,
          "posts": 3310,
          "timestamp": "2026-09-11T00:00:00Z"
        },
        {
          "bearish_posts": 681,
          "bullish_posts": 655,
          "posts": 2987,
          "timestamp": "2026-09-12T00:00:00Z"
        }
      ],
      "trending_asset": {
        "asset_class": "equity",
        "asset_id": "ORCL",
        "name": "Oracle Corporation",
        "symbol": "ORCL"
      }
    }
  ],
  "days": 30
}
```