All docs Nebula docs All endpoints Interactive docs Markdown OpenAPI JSON
  1. REST API
  2. Clusters

Cluster stances

GET /clusters/stances
GetClusterStances

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.

Parameters

cluster_id string QUERY 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.

Example:smart_money

asset_class array<string> QUERY

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.

Default:equity,commodity,index,crypto

days integer QUERY

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.

Allowed values
73090

Default:30

limit integer QUERY

Maximum assets returned.

Default:30

cURL Example

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'

Responses

200 OK
400 Bad Request
401 Unauthorized
402 Credits used up; upgrade_url links to buying more
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.

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

The asset's class: equity (stocks and ETFs), commodity, index, or crypto. Send it with asset_id on every asset-scoped request.

Allowed values
equitycommodityindexcrypto
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.

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