# Cluster stances

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

## Description

One cluster's net stance on its most-discussed assets, beside the market's.

Stance is (bullish − bearish) ÷ (bullish + bearish) posts, from −1 to +1. An asset needs 3 or more cluster posts and 20 or more market posts. `contrarian_share` is the share of those assets on which the cluster and the market lean opposite ways, both at least 0.1 from neutral; `peer_average_contrarian_share` is the same share averaged over the other clusters.

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/stances' \
  --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 stances 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.
- `limit` (integer, optional, default: 30, range: 1–100): Maximum assets returned.

## 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.
- `assets` (array<object>, required): The cluster's most-discussed eligible assets (3 or more cluster posts, 20 or more market posts), up to limit.
- `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.
- `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.
- `assets[].cluster_posts` (integer (int64), required): The cluster's posts about the asset over the window.
- `assets[].cluster_stance` (number (double), required): The cluster's net stance on the asset over the window: (bullish − bearish) / (bullish + bearish) posts, from −1 (all bearish) to +1 (all bullish).
- `assets[].market_stance` (number (double), required): The market's net stance on the same asset over the same window, on the same −1 to +1 scale, from every author except bots.
- `assets[].name` (string, required): Human-readable name.
- `assets[].symbol` (string, required): Display ticker or market symbol.
- `cluster_id` (string, required): The cluster analysed, as its canonical cluster_id.
- `contrarian_share` (number (double), required): Share of eligible assets on which the cluster and the market lean opposite ways, both at least 0.1 from neutral. Null under 5 assets.
- `days` (integer, required): Window length in complete UTC days, ending at the latest complete day.
- `peer_average_contrarian_share` (number (double), required): contrarian_share averaged over the other clusters; null when none has one.

Media type: `application/json`

## JSON Response

```json
{
  "asset_classes": [
    "equity",
    "commodity",
    "index",
    "crypto"
  ],
  "assets": [
    {
      "asset_class": "equity",
      "asset_id": "NVDA",
      "cluster_posts": 214,
      "cluster_stance": 0.62,
      "market_stance": 0.41,
      "name": "NVIDIA Corporation",
      "symbol": "NVDA"
    },
    {
      "asset_class": "equity",
      "asset_id": "TSLA",
      "cluster_posts": 137,
      "cluster_stance": -0.35,
      "market_stance": 0.22,
      "name": "Tesla, Inc.",
      "symbol": "TSLA"
    },
    {
      "asset_class": "equity",
      "asset_id": "AMZN",
      "cluster_posts": 96,
      "cluster_stance": 0.48,
      "market_stance": 0.3,
      "name": "Amazon.com, Inc.",
      "symbol": "AMZN"
    }
  ],
  "cluster_id": "smart_money",
  "contrarian_share": 0.1875,
  "days": 30,
  "peer_average_contrarian_share": 0.1123
}
```