# Call returns

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

## Description

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.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/calls/returns' \
  --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.
- `resolved_days` (integer, optional, default: 7): Resolved-outcome lookback in days.
- `clusters` (array<string>, optional): Repeatable canonical author-cluster filter. Use /clusters to discover current cluster IDs.

## Response

OK

- `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.

Media type: `application/json`

## JSON Response

```json
{
  "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
}
```