# Cluster trait comparison

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

## Description

Every behavioural trait across every cluster, for finding which groups are highest and lowest on each: the across-cluster form of /clusters/profile.

Each trait lists every cluster with a value, highest first, in the trait's unit. The traits and their definitions are those of /clusters/profile: earliness, contrarian, hype_fade, conviction, focus, breadth, bullishness, discovery, turnover, and coverage. A cluster with too little data for a trait is left out of that trait.

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/traits' \
  --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: 90, allowed: 30, 90, range: 30–90): How many complete UTC days to analyse, counting back from the latest complete day: 30 or 90. Longer windows see more hype cycles, so the cycle traits are steadier. 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

- `active_clusters` (integer, required): Clusters active in the window: the population traits are ranked within.
- `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.
- `days` (integer, required): Window length in complete UTC days, ending at the latest complete day.
- `hype_cycles` (integer, required): Market hype cycles in the window: assets whose posts peaked at 50 or more in a day and at least 3× their median day.
- `traits` (array<object>, required): One entry per trait, in the order earliness, contrarian, hype_fade, conviction, focus, breadth, bullishness, discovery, turnover, coverage.
- `traits[].clusters` (array<object>, required): Every cluster with a value for the trait, highest first.
- `traits[].clusters[].cluster_id` (string, required): Canonical author-cluster identifier.
- `traits[].clusters[].value` (number (double), required): The cluster's value for the trait, in unit.
- `traits[].trait` (string, required, enum: earliness, contrarian, hype_fade, conviction, focus, breadth, bullishness, discovery, turnover, coverage): The trait measured; the operation description defines each one.
- `traits[].unit` (string, required, enum: days, share, count): days, share (0 to 1) or count; fixed per trait.

Media type: `application/json`

## JSON Response

```json
{
  "active_clusters": 35,
  "asset_classes": [
    "equity",
    "commodity",
    "index",
    "crypto"
  ],
  "days": 90,
  "hype_cycles": 41,
  "traits": [
    {
      "clusters": [
        {
          "cluster_id": "early_movers",
          "value": 0.0875
        },
        {
          "cluster_id": "smart_money",
          "value": 0.0111
        },
        {
          "cluster_id": "late_movers",
          "value": -0.0917
        }
      ],
      "trait": "earliness",
      "unit": "days"
    },
    {
      "clusters": [
        {
          "cluster_id": "dao_funds",
          "value": 0.9912
        },
        {
          "cluster_id": "smart_money",
          "value": 0.8431
        },
        {
          "cluster_id": "doomers",
          "value": 0.3015
        }
      ],
      "trait": "bullishness",
      "unit": "share"
    }
  ]
}
```