# Author clusters

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

## Description

Returns social activity, author counts, activity change, and sentiment grouped by author cluster for one asset class. Defaults to equity when asset_class is omitted.

## cURL Example

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

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `asset_class` (string, optional, default: equity, 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: 24): Lookback window in hours.

## Response

OK

- `clusters` (array<object>, required): Author-cluster summaries for the selected asset class.
- `clusters[].activity_change_pct` (number (double)): Change from the previous equal-length window, in percentage points; absent when no comparison is possible.
- `clusters[].bearish_authors` (integer (int64), required): Distinct authors with bearish activity.
- `clusters[].bearish_posts` (number (double), required): Posts classified as bearish.
- `clusters[].bullish_authors` (integer (int64), required): Distinct authors with bullish activity.
- `clusters[].bullish_posts` (number (double), required): Posts classified as bullish.
- `clusters[].cluster_id` (string, required): Canonical author-cluster identifier.
- `clusters[].neutral_posts` (number (double), required): Posts classified as neutral.
- `clusters[].previous_total_posts` (number (double), required): Post count in the immediately preceding window of equal length.
- `clusters[].recent_sentiment_signal` (number (double), required): Net bullish sentiment signal over the trailing six hours.
- `clusters[].series` (array<object>, required): Chronologically ordered observations.
- `clusters[].series[].bearish_posts` (number (double), required): Posts classified as bearish.
- `clusters[].series[].bullish_posts` (number (double), required): Posts classified as bullish.
- `clusters[].series[].sentiment_signal` (number (double), required): Decay-weighted net bullish posts: bullish minus bearish. Positive is bullish, negative is bearish, and magnitude grows with activity.
- `clusters[].series[].timestamp` (string (date-time), required): UTC RFC 3339 timestamp for the observation or bucket start.
- `clusters[].series[].total_posts` (number (double), required): Post count over the metric's active lookback window.
- `clusters[].total_posts` (number (double), required): Post count over the metric's active lookback window.
- `clusters[].unique_authors` (integer (int64), required): Distinct authors in the requested window.
- `clusters[].window_sentiment_signal` (number (double), required): Net bullish sentiment signal over the complete requested window.
- `hours` (integer, required): Lookback window represented by the response, in hours.

Media type: `application/json`

## JSON Response

```json
{
  "clusters": [
    {
      "activity_change_pct": 18.4,
      "bearish_authors": 128,
      "bearish_posts": 438,
      "bullish_authors": 311,
      "bullish_posts": 1120,
      "cluster_id": "smart_money",
      "neutral_posts": 284,
      "previous_total_posts": 1556,
      "recent_sentiment_signal": 84.2,
      "series": [
        {
          "bearish_posts": 438,
          "bullish_posts": 1120,
          "sentiment_signal": 128.6,
          "timestamp": "2026-08-07T15:00:00Z",
          "total_posts": 1842
        }
      ],
      "total_posts": 1842,
      "unique_authors": 529,
      "window_sentiment_signal": 63.7
    }
  ],
  "hours": 168
}
```