> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Callout leaderboard

> GET /v1/callouts/leaderboard: your callers ranked for a period by average, median, best or summed peak multiple, hit rate or number of callouts, with their best call.

> [!NOTE]
>
> Callouts are switched on per instance on request. Contact us ([contact@cabalspy.xyz](mailto:contact@cabalspy.xyz)) to enable them. Without them every endpoint answers 403 [feature\_not\_enabled](https://docs.cabalspy.xyz/cabalspy-id/errors.md#feature_not_enabled).

Every user of your instance who made callouts in the period, ranked. A period covers the callouts **made** in that window back from now, each counted with its current [score](https://docs.cabalspy.xyz/cabalspy-id/callouts.md#scoring). Each entry carries the user's `external_id`, so you can render the leaderboard with your own user data.

> [!TIP]
>
> The leaderboard is cached for 30 seconds. To page through it, pass pagination.next\_cursor as cursor. An unknown or malformed cursor is answered with 400 invalid\_parameter.

## Query Parameters

**period** `string` (default: 7d)

Ranking window, one of 6h, 1d, 7d or 30d.

**chain** `string`

Only callouts on this chain. One of solana, bnb, base, eth, rh. Empty means every chain.

**sort** `string` (default: avg\_peak\_x)

Ranking order, highest first: avg\_peak\_x, median\_peak\_x, best\_peak\_x, sum\_peak\_x, hit\_rate or callouts. Ties go to the user with more callouts.

**min\_callouts** `integer` (default: 1)

Callouts a user needs in the period to be listed, 1 to 1,000.

**hit\_x** `number` (default: 2)

The multiple that counts as a hit, above 1 and at most 1000.

**limit** `integer` (default: 100)

Entries per page, 1 to 500.

**cursor** `string`

Cursor for the next page, the pagination.next\_cursor from the previous response.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

## Usage Example

```bash cURL theme={null}
curl "https://api-id.cabalspy.xyz/v1/callouts/leaderboard?period=7d&sort=avg_peak_x&min_callouts=3&limit=25" \
  -H "Authorization: Bearer YOUR_KEY"
```

```python Python theme={null}
import requests

params = {"period": "30d", "sort": "hit_rate", "min_callouts": 5, "hit_x": 3}
r = requests.get("https://api-id.cabalspy.xyz/v1/callouts/leaderboard", params=params,
                 headers={"Authorization": "Bearer YOUR_KEY"})
for e in r.json()["data"]["leaderboard"]:
    print(e["rank"], e["author"]["external_id"], e["callouts"], e["hit_rate"], e["best_call"]["symbol"])
```

```javascript JavaScript theme={null}
const p = new URLSearchParams({ period: "1d", chain: "solana", sort: "best_peak_x" });
const res = await fetch(`https://api-id.cabalspy.xyz/v1/callouts/leaderboard?${p}`, {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data } = await res.json();
data.leaderboard.forEach(e => console.log(e.rank, e.author?.username, e.best_peak_x));
```

## Response

**data** `object`

**data**

**period, chain, sort** `string`

The values used. chain is null for every chain.

**hit\_x** `number`

The hit multiple used.

**leaderboard** `array`

**entry**

**rank** `integer`

Position, starting at 1.

**csid\_id** `string`

The user's CabalSpy ID.

**author** `object`

csid\_id, external\_id, name, username, avatar\_url and kol, as in the [callout object](https://docs.cabalspy.xyz/cabalspy-id/callouts-list.md#the-callout-object).

**callouts** `integer`

Callouts in the period.

**avg\_peak\_x, median\_peak\_x, best\_peak\_x, sum\_peak\_x** `number`

Average, median, best and summed score.

**hits, hit\_rate** `number`

Callouts that reached hit\_x, and their percentage of the user's callouts (0 to 100).

**best\_call** `object`

The user's best callout in the period: id, chain, mint, symbol and peak\_x.

**pagination** `object`

limit, total (listed users), has\_more and next\_cursor (null means end).

```json Response theme={null}
{
  "success": true,
  "data": {
    "period": "7d",
    "chain": null,
    "sort": "avg_peak_x",
    "hit_x": 2.0,
    "leaderboard": [
      {
        "callouts": 4,
        "avg_peak_x": 2.3911,
        "median_peak_x": 1.8273,
        "best_peak_x": 4.48,
        "sum_peak_x": 9.5644,
        "hits": 2,
        "hit_rate": 50.0,
        "best_call": {
          "id": "5b0e7c3a-2d4f-4a6b-9c8d-1e2f3a4b5c6d",
          "chain": "solana",
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "symbol": "invisibull",
          "peak_x": 4.48
        },
        "rank": 1,
        "author": {
          "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
          "external_id": "user_8412",
          "name": "Maze",
          "username": "MazeCCC",
          "avatar_url": "https://cdn.example.com/avatars/8412.png",
          "kol": false
        },
        "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718"
      }
    ]
  },
  "pagination": {
    "limit": 100,
    "total": 1,
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": true,
    "cache_age_seconds": 12,
    "version": "v1",
    "timestamp": "2026-11-03T09:41:02Z"
  }
}
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | invalid\_parameter | period, chain, sort, min\_callouts, hit\_x, limit or cursor invalid. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | [feature\_not\_enabled](https://docs.cabalspy.xyz/cabalspy-id/errors.md#feature_not_enabled) | Callouts are not switched on for your instance. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.