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

Call returns

GET /calls/returns
GetCallReturns

Returns resolved call performance and a direction-aligned return distribution for one resolved asset. Omit both asset_id and asset_class for the all-market global view; asset_class cannot be used alone. Asset selectors support equities, commodities, indices, and crypto assets returned by GET /assets; commodity and index IDs use asset_class=equity. Parameter rules: asset_class requires asset_id. asset_id requires asset_class.

Parameters

asset_id string QUERY

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.

Example:NVDA

asset_class string QUERY

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.

Allowed values
equitycrypto

Example:equity

resolved_days integer QUERY

Resolved-outcome lookback in days.

Default:7

clusters array<string> QUERY

Repeatable canonical author-cluster filter. Use /clusters to discover current cluster IDs.

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 Credit balance exhausted
403 Forbidden
404 Not Found
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 after per-call return capping to limit outlier influence, 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; absent 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; absent for the last open-ended bucket.

losses
integer (int64) required

Resolved calls with a non-positive 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

Age after which a call is eligible for outcome resolution, in days.

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
}