# Social volume profile

- Method: `GET`
- Path: `/social-volume-profile`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-social-volume-profile/
- Interactive docs: https://docs.hiddensystems.ai/nebula/api/#endpoint=get-social-volume-profile

## Description

Returns social post activity distributed across the prices at which one resolved asset traded. Each bin includes sentiment imbalance, revisit count, balance, compression, significance, and point-of-control status. Asset selectors support equities, commodities, indices, and crypto assets returned by GET /assets; commodity and index IDs use asset_class=equity.

## cURL Example

```bash
curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/social-volume-profile' \
  --data-urlencode 'asset_id=NVDA' \
  --data-urlencode 'asset_class=equity' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `asset_id` (string, required): Canonical identifier returned by /assets. Stock, commodity, and index IDs are normally ticker or market symbols and use asset_class=equity; crypto IDs are canonical crypto slugs. asset_class is mandatory whenever asset_id is present.
- `asset_class` (string, required, allowed: equity, crypto): Namespace of asset_id, or the market class for endpoints with a class-scoped global view. Stocks, commodities, and indices use equity. Equity is the documented default only where the endpoint description states a default.
- `hours` (integer, optional, default: 168): Lookback window in hours.
- `bins` (integer, optional, default: 30): Number of price bins.
- `clusters` (array<string>, optional): Repeatable canonical author-cluster filter. Use /clusters to discover current cluster IDs.

## Response

OK

- `bins` (array<object>, required): Price bins ordered from low to high.
- `bins[].balance_score` (number (double), required): How evenly activity is split between directions, from 0 to 1.
- `bins[].bearish_posts` (number (double), required): Posts classified as bearish.
- `bins[].bearish_share` (number (double), required): Bearish share of directional posts in this bin, from 0 to 1.
- `bins[].bullish_posts` (number (double), required): Posts classified as bullish.
- `bins[].bullish_share` (number (double), required): Bullish share of directional posts in this bin, from 0 to 1.
- `bins[].compression_score` (number (double), required): How slowly price moved while in the bin, from 0 to 1.
- `bins[].directional_imbalance` (number (double)): Directional post imbalance (bullish − bearish) / (bullish + bearish), from −1 to 1; absent with no directional posts.
- `bins[].is_point_of_control` (boolean, required): True for the bin containing the greatest post activity.
- `bins[].neutral_posts` (number (double), required): Posts classified as neutral.
- `bins[].price_high_usd` (number (double), required): Exclusive upper edge of the price bin in US dollars.
- `bins[].price_low_usd` (number (double), required): Inclusive lower edge of the price bin in US dollars.
- `bins[].price_mid_usd` (number (double), required): Midpoint of the price bin in US dollars.
- `bins[].significance_score` (number (double), required): Composite prominence score for the bin, from 0 to 1.
- `bins[].total_posts` (number (double), required): Post count over the metric's active lookback window.
- `bins[].total_share` (number (double), required): Post count relative to the busiest bin, from 0 to 1.
- `bins[].visit_count` (integer, required): Separate times the market price entered this bin during the window.
- `maximum_posts_in_bin` (number (double), required): Post count in the busiest price bin.
- `maximum_price_usd` (number (double), required): Highest profile price in US dollars.
- `metadata` (object): Methodology and request-window metadata needed to interpret the response.
- `metadata.as_of` (string (date-time)): UTC time at which the metric was calculated.
- `metadata.bin_count` (integer, required): Number of requested price bins.
- `metadata.clusters` (array<string>): Results keyed or grouped by canonical author-cluster identifier.
- `metadata.hours` (integer, required): Lookback window represented by the response, in hours.
- `metadata.priced_buckets` (integer, required): Sentiment buckets successfully matched to a market price.
- `metadata.unpriced_buckets` (integer, required): Sentiment buckets omitted because no nearby market price was available.
- `minimum_price_usd` (number (double), required): Lowest profile price in US dollars.
- `point_of_control_bin_index` (integer): Zero-based index of the busiest bin; absent when the profile is empty.
- `total_posts` (number (double), required): Post count over the metric's active lookback window.

Media type: `application/json`

## JSON Response

```json
{
  "bins": [
    {
      "balance_score": 0.64,
      "bearish_posts": 438,
      "bearish_share": 0.32,
      "bullish_posts": 1120,
      "bullish_share": 0.68,
      "compression_score": 0.78,
      "directional_imbalance": 0.36,
      "is_point_of_control": true,
      "neutral_posts": 284,
      "price_high_usd": 180,
      "price_low_usd": 175,
      "price_mid_usd": 177.5,
      "significance_score": 0.87,
      "total_posts": 1842,
      "total_share": 0.82,
      "visit_count": 6
    }
  ],
  "maximum_posts_in_bin": 286,
  "maximum_price_usd": 188.75,
  "minimum_price_usd": 161.25,
  "point_of_control_bin_index": 14,
  "total_posts": 1842
}
```