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

Cluster trait comparison

GET /clusters/comparison/traits
CompareClusterTraits

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.

Parameters

asset_class array<string> QUERY

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.

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

Allowed values
3090

Default:90

cURL Example

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

Responses

200 OK
400 Bad Request
401 Unauthorized
402 Credits used up; upgrade_url links to buying more
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.

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

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