# Hype cycle arrivals

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

## Description

The window's biggest hype cycles and the order in which the clusters arrived in each.

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 response takes the `limit` cycles with the most posts on their peak day, then lists them most recent peak first; a cycle appears once the day after its peak is complete. For each cycle: the market's busiest hour of the peak day, its posts on the peak day, the market's posts hour by hour from 24 hours before that hour to 23 hours after, and `arrivals`, every cluster with 3 or more posts in those 48 hours, placed at the posts-weighted average hour of its posts relative to the peak hour, earliest first. Each cluster's average lead across every cycle is the `clusters` list of /clusters/hype-cycles.

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.

## cURL Example

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

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `asset_class` (array<string>, optional, default: equity,commodity,index,crypto, allowed: equity, commodity, index, crypto, comma-separated): 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.
- `days` (integer, optional, default: 30, allowed: 7, 30, 90, range: 7–90): How many complete UTC days of market peaks to include, counting back from the latest complete day: 7, 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.
- `limit` (integer, optional, default: 40, range: 1–100): Maximum hype cycles returned: the biggest by posts on their peak day.

## 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.
- `cycles` (array<object>, required): The window's biggest hype cycles, most recent peak first, up to limit.
- `cycles[].arrivals` (array<object>, required): Every cluster with 3 or more posts in the 48 hours around the peak hour, earliest first.
- `cycles[].arrivals[].cluster_id` (string, required): Canonical author-cluster identifier.
- `cycles[].arrivals[].offset_hours` (number (double), required): Hours from the market's peak hour to the posts-weighted average hour of the cluster's posts in the 48 hours around it. Negative is before the peak.
- `cycles[].arrivals[].posts` (integer (int64), required): The cluster's posts on the asset in the 48 hours around the peak hour.
- `cycles[].asset_class` (string, required, enum: equity, commodity, index, crypto): The asset's class: equity (stocks and ETFs), commodity, index, or crypto. Send it with asset_id on every asset-scoped request.
- `cycles[].asset_id` (string, required): Canonical public asset identifier: the ticker or market symbol for stocks, commodities, and indices, and the CoinGecko slug (or, without one, a numeric id) for crypto.
- `cycles[].name` (string, required): Human-readable name.
- `cycles[].peak_day_posts` (integer (int64), required): The market's posts on the asset on the peak day, bots left out.
- `cycles[].peak_timestamp` (string (date-time), required): UTC start of the market's busiest hour on the peak day.
- `cycles[].series` (array<object>, required): The market's posts on the asset hour by hour, from 24 hours before the peak hour to 23 hours after it: 48 observations.
- `cycles[].series[].posts` (integer (int32), required): The market's posts on the asset in the hour, bots left out.
- `cycles[].series[].timestamp` (string (date-time), required): UTC start of the hour.
- `cycles[].symbol` (string, required): Display ticker or market symbol.
- `days` (integer, required): Window length in complete UTC days, ending at the latest complete day.

Media type: `application/json`

## JSON Response

```json
{
  "asset_classes": [
    "equity",
    "commodity",
    "index",
    "crypto"
  ],
  "cycles": [
    {
      "arrivals": [
        {
          "cluster_id": "smart_money",
          "offset_hours": -3.2,
          "posts": 18
        },
        {
          "cluster_id": "team_leaders",
          "offset_hours": -2.1,
          "posts": 9
        },
        {
          "cluster_id": "media",
          "offset_hours": 1.4,
          "posts": 57
        }
      ],
      "asset_class": "equity",
      "asset_id": "ORCL",
      "name": "Oracle Corporation",
      "peak_day_posts": 930,
      "peak_timestamp": "2026-09-10T14:00:00Z",
      "series": [
        {
          "posts": 41,
          "timestamp": "2026-09-10T13:00:00Z"
        },
        {
          "posts": 112,
          "timestamp": "2026-09-10T14:00:00Z"
        },
        {
          "posts": 64,
          "timestamp": "2026-09-10T15:00:00Z"
        }
      ],
      "symbol": "ORCL"
    }
  ],
  "days": 30
}
```