# Cluster overlap

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

## Description

Which other clusters watch the same assets as this one, and whether they lean the same way.

- `overlap_share`: the share of this cluster's 50 most-discussed assets that are also in the peer's.
- `direction_agreement_share`: on shared assets where both clusters lean at least 0.05 away from the market's stance, the share where they lean the same way. Null below 3 assets.
- `stance_gap`: this cluster's stance minus the peer's, averaged over shared assets. Positive means this cluster is the more bullish.

Peers are sorted by overlap, each with up to 5 shared assets.

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/overlap' \
  --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: 30, allowed: 7, 30, 90, range: 7–90): How many complete UTC days to measure focus over, 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.

## 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.
- `days` (integer, required): Window length in complete UTC days, ending at the latest complete day.
- `peers` (array<object>, required): Every other active cluster, most-overlapping first.
- `peers[].agreeing_asset_count` (integer, required): Compared assets on which both clusters lean the same way relative to the market.
- `peers[].cluster_id` (string, required): Canonical author-cluster identifier.
- `peers[].compared_asset_count` (integer, required): Shared assets, across the whole overlap, on which both clusters lean at least 0.05 from the market's stance.
- `peers[].direction_agreement_share` (number (double), required): On shared assets where both clusters lean at least 0.05 from the market's stance, the share where they lean the same way: agreeing_asset_count ÷ compared_asset_count. Null under 3 assets.
- `peers[].overlap_share` (number (double), required): Share of this cluster's focus set also in the peer's, from 0 to 1.
- `peers[].shared_assets` (array<object>, required): Up to 5 assets in both focus sets, in this cluster's order of attention.
- `peers[].shared_assets[].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.
- `peers[].shared_assets[].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.
- `peers[].shared_assets[].cluster_stance` (number (double), required): This cluster's net stance on the asset, from −1 to +1. Null under 3 bullish or bearish posts.
- `peers[].shared_assets[].market_stance` (number (double), required): The market's net stance on the asset, from −1 to +1: the baseline both leans are measured against. Null under 3 bullish or bearish posts.
- `peers[].shared_assets[].name` (string, required): Human-readable name.
- `peers[].shared_assets[].peer_stance` (number (double), required): The peer's net stance on the asset, from −1 to +1. Null under 3 bullish or bearish posts.
- `peers[].shared_assets[].symbol` (string, required): Display ticker or market symbol.
- `peers[].stance_gap` (number (double), required): This cluster's stance minus the peer's, averaged over shared assets both have a stance on, from −2 to +2. Positive means this cluster is more bullish. Null under 3 assets.
- `top_asset_count` (integer, required): Size of each cluster's focus set: its most-discussed assets, up to this many.

Media type: `application/json`

## JSON Response

```json
{
  "asset_classes": [
    "equity",
    "commodity",
    "index",
    "crypto"
  ],
  "cluster_id": "smart_money",
  "days": 30,
  "peers": [
    {
      "agreeing_asset_count": 11,
      "cluster_id": "fa_analyst",
      "compared_asset_count": 17,
      "direction_agreement_share": 0.6471,
      "overlap_share": 0.62,
      "shared_assets": [
        {
          "asset_class": "equity",
          "asset_id": "NVDA",
          "cluster_stance": 0.62,
          "market_stance": 0.41,
          "name": "NVIDIA Corporation",
          "peer_stance": 0.54,
          "symbol": "NVDA"
        },
        {
          "asset_class": "equity",
          "asset_id": "AMZN",
          "cluster_stance": 0.48,
          "market_stance": 0.3,
          "name": "Amazon.com, Inc.",
          "peer_stance": null,
          "symbol": "AMZN"
        }
      ],
      "stance_gap": 0.0812
    },
    {
      "agreeing_asset_count": 5,
      "cluster_id": "kols",
      "compared_asset_count": 12,
      "direction_agreement_share": 0.4167,
      "overlap_share": 0.46,
      "shared_assets": [
        {
          "asset_class": "equity",
          "asset_id": "NVDA",
          "cluster_stance": 0.62,
          "market_stance": 0.41,
          "name": "NVIDIA Corporation",
          "peer_stance": 0.71,
          "symbol": "NVDA"
        },
        {
          "asset_class": "equity",
          "asset_id": "TSLA",
          "cluster_stance": -0.35,
          "market_stance": 0.22,
          "name": "Tesla, Inc.",
          "peer_stance": 0.28,
          "symbol": "TSLA"
        }
      ],
      "stance_gap": -0.1375
    }
  ],
  "top_asset_count": 50
}
```