# Screener

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

## Description

Screen assets or subjects by attention, sentiment, and price: rank by one measure, keep only results inside the ranges you set on the others. /top-trending and /top-momentum are this screen with no filters, sorted by `share` and `share_change`.

Every measure covers the last 24 hours, compared with the 24 hours before. `share` and `share_change` are defined as on /top-trending and /top-momentum; `posts` counts posts; `net_bullish_posts` is bullish minus bearish posts, so negative values mean a bearish conversation; `price_change_24h_pct` is the 24-hour price move. Ranges are inclusive and combine with AND. A range on price, or sorting by it, applies to assets only and leaves out assets with no price. Sort `order` is descending by default; results without a value for the sort measure come last either way. Share is measured against the whole conversation about the same kind of thing over the same 24 hours: all traditional-market posts for stocks, commodities, and indices, all crypto posts for crypto, and all person, account, and topic posts for subjects. Bot accounts are left out. Filter by author cluster to rank what one group is talking about, for example `clusters=smart_money`; share is then measured against everything the selected clusters posted, and several clusters are added together. Each result's `asset_id` and `asset_class`, or `subject_id`, can be passed straight to the other endpoints.

Parameter rules:
- `asset_class` applies only to `kind=asset`.
- Posting communities such as `wallstreetbets` are accepted only for `kind=asset` with `asset_class` equity, commodity, or index.

Parameter rules:
- Each minimum must not exceed its maximum.
- Price sorting and price ranges need `kind=asset`.
- Unknown parameters return 400, so a misspelt filter never widens the screen.

## cURL Example

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

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `kind` (string, optional, default: asset, allowed: asset, subject): What to rank: asset (stocks, commodities, indices, or crypto) or subject (people, accounts, and topics). Defaults to asset.
- `asset_class` (string, optional, default: equity, allowed: equity, commodity, index, crypto): With kind=asset, the market to rank: equity (stocks and ETFs), commodity, index, or crypto. Defaults to equity. Commodities and indices are ranked by their share of all traditional-market conversation, the same population as stocks.
- `clusters` (array<string>, optional): Filters to posts from one or more author clusters. Repeat the parameter to combine groups, for example `clusters=kols&clusters=media`. Selected clusters are added together, so an author who belongs to two selected clusters counts once for each. Nebula sorts authors into more than 30 clusters by who they are and how they behave, and an author can belong to several:
  - Callers, ranked daily on their last 90 days of calls: `smart_money` (the best-ranked callers by win rate and return), `dumb_money` (the worst-ranked), and `top_degens` (the best callers on small-cap crypto)
  - Builders: `developers`, `founders`, `team_leaders` (CEOs and other executives), and `project_accounts`
  - Institutions: `vcs`, `asset_managers`, `dao_guild_funds`, `incubators`, and `exchanges`
  - Influence: `kols`, `celebrities`, `media`, `marketer`, and `shiller`
  - Analysts: `ta_analyst`, `fa_analyst`, `macro_analyst`, `onchain_analyst`, and `investigators`
  - Traders by horizon: `position_trader`, `swing_trader`, and `day_trader`
  - Bias: `perma_bull`, `doomer`, and `tribalist`
  - Other: `political`, `nft`, `bots`, and `automated_ai`
  - Communities, by where a post was made rather than who wrote it: `wallstreetbets` (r/wallstreetbets) and `reddit` (anywhere on Reddit)
  An unknown cluster id returns 400. Use /clusters to see which clusters are active in a market.
- `sort` (string, optional, default: share, allowed: share, share_change, share_change_pct, posts, net_bullish_posts, price_change_24h_pct): The measure to rank by. Defaults to share.
- `order` (string, optional, default: desc, allowed: desc, asc): desc (the default) puts the highest values first; asc puts the lowest first.
- `limit` (integer, optional, default: 25): Maximum results returned.
- `min_share` (number, optional): Keep results whose share is at least this fraction of the conversation, from 0 to 1.
- `max_share` (number, optional): Keep results whose share is at most this fraction, from 0 to 1.
- `min_share_change` (number, optional): Keep results whose share rose by at least this much against the previous 24 hours, as a fraction from -1 to 1: 0.01 is one percentage point.
- `max_share_change` (number, optional): Keep results whose share changed by at most this much, as a fraction from -1 to 1; negative values select results losing share.
- `min_posts` (integer, optional): Keep results with at least this many posts over the 24 hours. Defaults to 5 when sorting by price_change_24h_pct, so thinly discussed names do not lead the ranking; send min_posts=1 to include them.
- `min_net_bullish_posts` (integer, optional): Keep results with at least this many more bullish than bearish posts; negative values allow bearish results.
- `max_net_bullish_posts` (integer, optional): Keep results with at most this many more bullish than bearish posts; negative values select bearish results.
- `min_price_change_24h_pct` (number, optional): Keep assets whose 24-hour price change is at least this many percent.
- `max_price_change_24h_pct` (number, optional): Keep assets whose 24-hour price change is at most this many percent.

## Response

OK

- `asset_class` (string): The market whose assets were ranked; absent for subjects.
- `clusters` (array<string>, required): The author clusters whose posts were counted, canonicalised; empty when every author except bots was counted.
- `from` (string (date-time), required): UTC start of the ranked 24 hours. The comparison window is the 24 hours before it.
- `kind` (string, required, enum: asset, subject): What was ranked: asset or subject, as requested.
- `previous_total_posts` (integer (int64), required): All posts in the ranked population over the previous 24 hours.
- `results` (array<object>, required): Ranked results, best first.
- `results[].asset_class` (string, 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.
- `results[].asset_id` (string): Canonical public asset identifier. Equity identifiers are ticker symbols; crypto identifiers are canonical crypto IDs.
- `results[].bearish_posts` (integer (int64), required): Posts classified as bearish.
- `results[].bullish_posts` (integer (int64), required): Posts classified as bullish.
- `results[].kind` (string, required, enum: asset, subject): What the result is: asset (query it with asset_id and asset_class) or subject (query it with subject_id).
- `results[].name` (string, required): Human-readable name.
- `results[].neutral_posts` (integer (int64), required): Posts classified as neutral.
- `results[].posts` (integer (int64), required): This result's posts over the ranked 24 hours.
- `results[].previous_posts` (integer (int64), required): This result's posts in the immediately preceding window of equal length.
- `results[].price_change_24h_pct` (number (double)): Raw market-price change over 24 hours, in percentage points.
- `results[].share` (number (double), required): This result's posts as a fraction of all posts in the ranked population over the same 24 hours, from 0 to 1.
- `results[].share_change` (number (double)): Change in share against the previous window, as a decimal fraction: 0.01 is one percentage point. Absent only when the population had no posts in the previous window.
- `results[].share_change_pct` (number (double)): The change in share relative to the previous window's share, in percent. Absent when the result had no posts in the previous window.
- `results[].subject_id` (string): Canonical identifier for a non-asset person, account, or topic.
- `results[].symbol` (string): Display ticker or market symbol.
- `to` (string (date-time), required): UTC end of the ranked 24 hours: when the ranking was computed.
- `total_posts` (integer (int64), required): All posts in the ranked population over the 24 hours: the denominator of share.

Media type: `application/json`

## JSON Response

```json
{
  "asset_class": "equity",
  "clusters": [],
  "from": "2026-08-06T15:00:00Z",
  "kind": "asset",
  "previous_total_posts": 17205,
  "results": [
    {
      "asset_class": "equity",
      "asset_id": "NVDA",
      "bearish_posts": 61,
      "bullish_posts": 214,
      "kind": "asset",
      "name": "NVIDIA Corporation",
      "neutral_posts": 111,
      "posts": 386,
      "previous_posts": 273,
      "price_change_24h_pct": -2.48,
      "share": 0.025255,
      "share_change": 0.009388,
      "share_change_pct": 59.16,
      "symbol": "NVDA"
    },
    {
      "asset_class": "equity",
      "asset_id": "AMZN",
      "bearish_posts": 30,
      "bullish_posts": 92,
      "kind": "asset",
      "name": "Amazon.com, Inc.",
      "neutral_posts": 63,
      "posts": 185,
      "previous_posts": 165,
      "price_change_24h_pct": -0.32,
      "share": 0.012104,
      "share_change": 0.002516,
      "share_change_pct": 26.24,
      "symbol": "AMZN"
    }
  ],
  "to": "2026-08-07T15:00:00Z",
  "total_posts": 15284
}
```