# Cluster hype cycles

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

## Description

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

## cURL Example

```bash
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'
```

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

## Response

OK

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

Media type: `application/json`

## JSON Response

```json
{
  "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
}
```