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

Calls outcome distribution

GET /calls/returns
GetCallReturns

How recent calls have performed: win rate, median and average return, and the distribution of returns. Each call is scored on the price move over the 24 hours after it, from the caller's side, so a short call on a 10% drop is +10%. Send clusters to compare groups, for example smart_money against dumb_money.

Parameter rules:

  • Send asset_class and asset_id together, or neither.

Wallet payment available at https://nebula-api.hiddensystems.ai/api/v1/x402/calls/returns. No Nebula account or API key required; check the payment offer before signing. x402 payment guide.

Parameters

asset_id string QUERY

Asset ID from /assets or /search, such as NVDA, GLD, SPX, or bitcoin. Send it with the asset_class returned alongside it.

Example:NVDA

asset_class string QUERY

Class of the asset named by asset_id: equity (stocks and ETFs), commodity, index, or crypto. Send the asset_class that /assets or /search returned alongside the asset_id.

Allowed values
equitycommodityindexcrypto

Example:equity

resolved_days integer QUERY

How many days of resolved calls to include: calls whose 24-hour mark passed within this many days. Free plans reach back 90 days; further returns 403.

Default:7

clusters array<string> QUERY

Author clusters to read; repeat to combine, for example clusters=kols&clusters=media. Selected clusters are added together, and an author can belong to several.

  • Callers: smart_money (best-performing callers), dumb_money (worst-performing), top_degens (best on small-cap crypto)
  • Timing: early_movers (first to talk about an asset as attention rises), late_movers (arrive at the peak or after)
  • Builders: developers, founders, team_leaders, project_accounts
  • Institutions: vcs, asset_managers, dao_guild_funds, incubators, exchanges
  • Influence: kols, celebrities, media, marketer, shiller
  • Analysts: ta_analyst, fa_analyst, macro_analyst, onchain_analyst, investigators
  • Traders: position_trader, swing_trader, day_trader
  • Bias: perma_bull, doomer, tribalist
  • Other: political, nft, bots, automated_ai

Example:smart_money

cURL Example

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

Responses

200 OK
400 Bad Request
401 Unauthorized
402 Credits used up; response includes renewal timing and purchased credit balance
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

average_return_pct
number (double) required

Mean direction-aligned return across resolved calls, in percentage points.

buckets
array<object> required

Return-distribution buckets in ascending order.
buckets[].call_count
integer (int64) required

Resolved calls in this return bucket.

buckets[].capped_total_aligned_return_pct
number (double) required

Sum of direction-aligned returns with each call capped at ±100%, in percentage points.

buckets[].label
string required

Human-readable bucket or index label.

buckets[].lower_bound_pct
number (double) required

Inclusive lower return bound in percentage points; null for the first, open-ended bucket.

buckets[].total_aligned_return_pct
number (double) required

Sum of direction-aligned returns in this bucket, in percentage points.

buckets[].upper_bound_pct
number (double) required

Exclusive upper return bound in percentage points; null for the last, open-ended bucket.

losses
integer (int64) required

Resolved calls with a negative direction-aligned return.

median_return_pct
number (double) required

Median direction-aligned return across resolved calls, in percentage points.

resolved_calls
integer (int64) required

Number of calls with a resolved outcome.

resolved_days
integer required

How many days of resolved calls the statistics include.

win_rate_pct
number (double) required

Winning resolved calls as a percentage from 0 to 100.

wins
integer (int64) required

Resolved calls with a positive direction-aligned return.

{
  "average_return_pct": 4.1,
  "buckets": [
    {
      "call_count": 91,
      "capped_total_aligned_return_pct": -228,
      "label": "-10% to 0%",
      "lower_bound_pct": -10,
      "total_aligned_return_pct": -342.5,
      "upper_bound_pct": 0
    }
  ],
  "losses": 174,
  "median_return_pct": 2.8,
  "resolved_calls": 412,
  "resolved_days": 7,
  "win_rate_pct": 57.77,
  "wins": 238
}