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

Cluster hype cycles

GET /clusters/hype-cycles
GetClusterHypeCycles

How one cluster's attention builds around hype-cycle peaks compared with the market's.

curve is the average cumulative percentage of each side's posts by day_offset, from 7 days before the peak to 7 after. Both lines end at 100, so the line further left is earlier. lead_days is the profile's earliness: how far ahead of everyone else the cluster's posts arrive within 24 hours of the market's peak hour (positive is early). clusters ranks every cluster's lead, earliest first, with an 80% bootstrap range.

A hype cycle is an asset whose market posts peaked at 50 or more in a day and at least 3× its median day; the cluster joins one with 3 or more posts within 7 days of the peak.

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.

Parameters

cluster_id string QUERY 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.

Example:smart_money

asset_class array<string> QUERY

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.

Default:equity,commodity,index,crypto

days integer QUERY

How many complete UTC days of market peaks to include, counting back from the latest complete day: 30 or 90. 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 --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/clusters/hype-cycles' \
  --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; 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

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.

clusters
array<object> required

Every cluster with a lead (5 or more cycles), earliest first, the requested one included.
clusters[].cluster_id
string required

The cluster, as its canonical cluster_id.

clusters[].cycles_joined
integer required

Completed hype cycles in which the cluster posted within 24 hours of the market's peak hour.

clusters[].lead_days
number (double) required

The cluster's lead in days, computed as the top-level lead_days. Positive is early.

clusters[].lead_high_days
number (double) required

90th percentile of lead_days over 400 bootstrap resamples.

clusters[].lead_low_days
number (double) required

10th percentile of lead_days over 400 bootstrap resamples.

curve
array<object> required

The average cumulative build-up, one point per day_offset from −7 to +7; empty when no cycle has completed.
curve[].cluster_cumulative_pct
number (double) required

Percentage of the cluster's posts in the 15 days around the peak made by the end of this day, averaged over cycles; 100 at day_offset 7.

curve[].day_offset
integer required

Days from the market peak: negative before it, 0 on the peak day, positive after it.

curve[].market_cumulative_pct
number (double) required

The same for the market, over the same cycles.

cycles_joined
integer required

Completed hype cycles the cluster joined: 3 or more posts within 7 days of the peak.

days
integer required

Window length in complete UTC days, ending at the latest complete day.

lead_days
number (double) required

How far ahead of everyone else the cluster's posts arrive within 24 hours of the market's peak hour, in days. Positive is early; null under 20 cycles.

{
  "asset_classes": [
    "equity",
    "commodity",
    "index",
    "crypto"
  ],
  "cluster_id": "smart_money",
  "clusters": [
    {
      "cluster_id": "wallstreetbets",
      "cycles_joined": 171,
      "lead_days": 0.0542,
      "lead_high_days": 0.0708,
      "lead_low_days": 0.0417
    },
    {
      "cluster_id": "smart_money",
      "cycles_joined": 471,
      "lead_days": 0.0125,
      "lead_high_days": 0.0292,
      "lead_low_days": -0.0083
    },
    {
      "cluster_id": "exchanges",
      "cycles_joined": 466,
      "lead_days": -0.0667,
      "lead_high_days": -0.0542,
      "lead_low_days": -0.0792
    }
  ],
  "curve": [
    {
      "cluster_cumulative_pct": 46.8,
      "day_offset": -1,
      "market_cumulative_pct": 38.2
    },
    {
      "cluster_cumulative_pct": 63.5,
      "day_offset": 0,
      "market_cumulative_pct": 57.9
    },
    {
      "cluster_cumulative_pct": 73.1,
      "day_offset": 1,
      "market_cumulative_pct": 69.4
    }
  ],
  "cycles_joined": 27,
  "days": 90,
  "lead_days": 0.0125
}