All docs Nebula docs All endpoints Interactive docs Markdown OpenAPI JSON
  1. REST API
  2. Clusters

Cluster profile

GET /clusters/profile
GetClusterProfile

One cluster's behavioural traits, each ranked against every other cluster (rank 1 is the highest):

  • earliness (days): how early it posts around hype-cycle peaks; positive is early.
  • contrarian (share): assets where it leans the opposite way to the market.
  • hype_fade (days): positive means it turns less bullish as hype builds.
  • conviction (days): how long it holds the same view on an asset.
  • focus (share): posts on its top 5 assets.
  • breadth (count): assets it discusses.
  • bullishness (share): bullish share of its bullish and bearish posts.
  • discovery (share): posts on assets outside the market's top 100.
  • turnover (share): how much its top 10 assets change week to week.
  • coverage (share): hype cycles it took part in.

A hype cycle is a day an asset's posts spike to at least 3× normal. Complete UTC days only.

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/profile. 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

days integer QUERY

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 reach back 90 days; further returns 403.

Allowed values
3090

Default:90

cURL Example

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'

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

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

The trait measured; the operation description defines each one.

Allowed values
earlinesscontrarianhype_fadeconvictionfocusbreadthbullishnessdiscoveryturnovercoverage
traits[].unit
string required

days, share (0 to 1) or count; fixed per trait.

Allowed values
dayssharecount
traits[].value
number (double) required

The cluster's value for this trait, in unit; null when the cluster has too little data for it.

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