# Cluster profile

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

## Description

One cluster's behavioural traits, each ranked against every other cluster.

- `earliness` (days): how far ahead of everyone else its posts arrive around hype-cycle peaks, within 24 hours of the market's peak hour. Positive is early. Needs 20 cycles.
- `contrarian` (share): assets where it and the market lean clearly opposite ways (both stances at least 0.1 from neutral).
- `hype_fade` (days): how far its bullish posts lead its posts overall around peaks. Positive means it cooled into the hype.
- `conviction` (days): average length of its same-direction runs on an asset.
- `focus` (share): posts on its 5 most-discussed assets.
- `breadth` (count): assets with 3 or more posts.
- `bullishness` (share): bullish ÷ (bullish + bearish) posts.
- `discovery` (share): posts on assets outside the market's 100 most-discussed.
- `turnover` (share): week-to-week change in its top 10 assets; 0 is unchanged, 1 all new.
- `coverage` (share): hype cycles it joined (3 or more posts within 7 days of the peak).

A hype cycle is an asset whose market posts peaked at 50 or more in a day and at least 3× its median day. `rank` 1 is the highest value, `percentile` runs from 0 to 1, and `peer_values` holds every other cluster's value. A trait is null when there is too little data.

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/profile' \
  --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.
- `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.
- `cluster_id` (string, required): The cluster analysed, as its canonical cluster_id.
- `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[].peer_values` (array<number (double)>, required): Every other cluster's value for this trait, ascending.
- `traits[].percentile` (number (double), required): From 0 (lowest) to 1 (highest) among clusters with a value. Null when value is null.
- `traits[].rank` (integer, required): 1 is the highest value; tied clusters share the better rank. Null when value is null.
- `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.
- `traits[].value` (number (double), required): The cluster's value for this trait, in unit; null when the cluster has too little data for it.

Media type: `application/json`

## JSON Response

```json
{
  "active_clusters": 34,
  "asset_classes": [
    "equity",
    "commodity",
    "index",
    "crypto"
  ],
  "cluster_id": "smart_money",
  "days": 90,
  "hype_cycles": 41,
  "traits": [
    {
      "peer_values": [
        -1.8,
        -0.64,
        0.12,
        0.87,
        2.05
      ],
      "percentile": 0.9394,
      "rank": 3,
      "trait": "earliness",
      "unit": "days",
      "value": 1.42
    },
    {
      "peer_values": [
        0.041,
        0.083,
        0.112,
        0.204,
        0.267
      ],
      "percentile": 0.7576,
      "rank": 9,
      "trait": "contrarian",
      "unit": "share",
      "value": 0.1875
    },
    {
      "peer_values": [
        -1.1,
        -0.3,
        0.2,
        0.9,
        1.4
      ],
      "percentile": 0.8182,
      "rank": 7,
      "trait": "hype_fade",
      "unit": "days",
      "value": 0.6
    },
    {
      "peer_values": [
        1.4,
        1.9,
        2.2,
        2.8,
        3.6
      ],
      "percentile": 0.6667,
      "rank": 12,
      "trait": "conviction",
      "unit": "days",
      "value": 2.35
    },
    {
      "peer_values": [
        0.18,
        0.24,
        0.35,
        0.47,
        0.72
      ],
      "percentile": 0.4242,
      "rank": 20,
      "trait": "focus",
      "unit": "share",
      "value": 0.31
    },
    {
      "peer_values": [
        41,
        96,
        188,
        405,
        1270
      ],
      "percentile": 0.8485,
      "rank": 6,
      "trait": "breadth",
      "unit": "count",
      "value": 312
    },
    {
      "peer_values": [
        0.52,
        0.64,
        0.71,
        0.78,
        0.86
      ],
      "percentile": 0.6061,
      "rank": 14,
      "trait": "bullishness",
      "unit": "share",
      "value": 0.7412
    },
    {
      "peer_values": [
        0.09,
        0.17,
        0.26,
        0.38,
        0.61
      ],
      "percentile": 0.5152,
      "rank": 17,
      "trait": "discovery",
      "unit": "share",
      "value": 0.2837
    },
    {
      "peer_values": [
        0.18,
        0.27,
        0.36,
        0.44,
        0.58
      ],
      "percentile": 0.3939,
      "rank": 21,
      "trait": "turnover",
      "unit": "share",
      "value": 0.3455
    },
    {
      "peer_values": [
        0.05,
        0.22,
        0.41,
        0.63,
        0.88
      ],
      "percentile": 0.7879,
      "rank": 8,
      "trait": "coverage",
      "unit": "share",
      "value": 0.6585
    }
  ]
}
```