# Related subjects

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

## Description

Returns the non-asset subjects most frequently discussed in the same posts as exactly one resolved asset or non-asset subject. Each row includes shared activity and the anchor's sentiment within that conversation. Asset selectors support equities, commodities, indices, and crypto assets returned by GET /assets; commodity and index IDs use asset_class=equity. Parameter rules: One of asset_id or subject_id is required. asset_id requires asset_class. subject_id and asset_class cannot be combined. subject_id and asset_id cannot be combined.

## cURL Example

```bash
curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/related-subjects' \
  --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, optional): 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, optional, 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.
- `subject_id` (string, optional): Canonical non-asset identifier returned by /subjects. It cannot be combined with asset_id or asset_class.
- `hours` (integer, optional, default: 168): Lookback window in hours.
- `limit` (integer, optional, default: 25): Maximum results returned.

## Response

OK

- `authors` (integer (int64), required): Distinct authors represented by the matching posts.
- `average_sentiment_score` (number (double), required): Mean sentiment score across all anchor posts in the requested window.
- `from` (string (date-time), required): Inclusive UTC start of the measured window.
- `hours` (integer, required): Lookback window represented by the response, in hours.
- `posts` (integer (int64), required): Matching post count over the requested window.
- `subjects` (array<object>, required): Non-asset subjects returned by the discovery operation.
- `subjects[].authors` (integer (int64), required): Distinct authors represented by the matching posts.
- `subjects[].bearish_posts` (integer (int64), required): Posts classified as bearish.
- `subjects[].bullish_posts` (integer (int64), required): Posts classified as bullish.
- `subjects[].first_post_at` (string (date-time)): UTC time of the first matching post in the requested window.
- `subjects[].last_post_at` (string (date-time)): UTC time of the latest matching post in the requested window.
- `subjects[].name` (string, required): Human-readable name.
- `subjects[].neutral_posts` (integer (int64), required): Posts classified as neutral.
- `subjects[].posts` (integer (int64), required): Matching post count over the requested window.
- `subjects[].posts_delta` (number (double), required): Fractional change from posts_prior to posts_recent; positive values indicate growth.
- `subjects[].posts_prior` (integer (int64), required): Matching posts in the first half of the requested window.
- `subjects[].posts_recent` (integer (int64), required): Matching posts in the second half of the requested window.
- `subjects[].sentiment_delta` (number (double), required): Difference between sentiment_score for the shared conversation and the anchor's complete-window average.
- `subjects[].sentiment_score` (number (double), required): Signed sentiment score; positive is bullish and negative is bearish.
- `subjects[].share` (number (double), required): Anchor posts that also mention this subject as a decimal fraction of all anchor posts in the window.
- `subjects[].subject_id` (string, required): Canonical identifier for a non-asset person, account, or topic.
- `to` (string (date-time), required): Exclusive UTC end of the measured window.

Media type: `application/json`

## JSON Response

```json
{
  "authors": 241,
  "average_sentiment_score": 36.2,
  "from": "2026-08-15T09:00:00Z",
  "hours": 168,
  "posts": 684,
  "subjects": [
    {
      "authors": 73,
      "bearish_posts": 41,
      "bullish_posts": 112,
      "first_post_at": "2026-08-15T09:00:00Z",
      "last_post_at": "2026-08-22T08:45:00Z",
      "name": "Artificial Intelligence",
      "neutral_posts": 31,
      "posts": 184,
      "posts_delta": 0.515,
      "posts_prior": 272,
      "posts_recent": 412,
      "sentiment_delta": 8.4,
      "sentiment_score": 42.6,
      "share": 0.148,
      "subject_id": "text:artificial intelligence"
    }
  ],
  "to": "2026-08-22T09:00:00Z"
}
```