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 early one cluster arrives at hype cycles compared with the market. curve is the cumulative share of each side's posts from 7 days before a peak to 7 after, so the line further left is earlier; lead_days is the cluster's lead (positive is early), and clusters ranks every cluster's lead.

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/hype-cycles. 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 of market peaks to include, counting back from the latest complete day: 30 or 90. 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/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; 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

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

High end of the likely range of lead_days.

clusters[].lead_low_days
number (double) required

Low end of the likely range of lead_days.

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
}