> ## 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 stats

> GET /v1/callouts/stats: one user's callout record for the last 6 hours, day, 7 days and 30 days: callouts, average, median and best peak multiple, hit rate and the average multiple right now.

> [!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).

One user's callout record, for four periods at once: 6h, 1d, 7d and 30d. A period covers the callouts the user **made** in that window back from now, each counted with its current [score](https://docs.cabalspy.xyz/cabalspy-id/callouts.md#scoring), so a callout from yesterday that keeps rising improves the 1d, 7d and 30d numbers.

The same block is part of the [platform user profile](https://docs.cabalspy.xyz/cabalspy-id/platform-users-profile.md) as `callouts`, with the default `hit_x` of 2.

## Query Parameters

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id: a platform user, or a person who signed in to your app with CabalSpy ID (no `thesis` scope needed).

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

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

**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/stats?external_id=user_8412&hit_x=3" \
  -H "Authorization: Bearer YOUR_KEY"
```

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

d = requests.get("https://api-id.cabalspy.xyz/v1/callouts/stats",
                 params={"external_id": "user_8412"},
                 headers={"Authorization": "Bearer YOUR_KEY"}).json()["data"]
for period, s in d["periods"].items():
    print(period, s["callouts"], s["avg_peak_x"], f'{s["hit_rate"]}% hit {d["hit_x"]}x')
```

```javascript JavaScript theme={null}
const p = new URLSearchParams({ external_id: "user_8412" });
const res = await fetch(`https://api-id.cabalspy.xyz/v1/callouts/stats?${p}`, {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data } = await res.json();
console.log(data.periods["7d"].avg_peak_x, data.callouts_all_time);
```

## Response

**data** `object`

**data**

**user** `object`

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

**hit\_x** `number`

The hit multiple used.

**periods** `object`

One entry each for `6h`, `1d`, `7d` and `30d`.

**period**

**callouts** `integer`

Callouts made in the period.

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

Average, median and best score. Null without callouts.

**sum\_peak\_x** `number`

Sum of the scores.

**hits** `integer`

Callouts whose score reached hit\_x.

**hit\_rate** `number`

Hits as a percentage of callouts, 0 to 100.

**avg\_now\_x** `number`

Average current multiple: the latest price against the entry, the same entry as `now.x` in the callout object. Null without a price read.

**tracking** `integer`

How many of these callouts are still tracked.

**callouts\_all\_time** `integer`

All callouts of the user on your instance, removed ones excluded.

```json Response theme={null}
{
  "success": true,
  "data": {
    "user": {
      "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
    },
    "hit_x": 2.0,
    "periods": {
      "6h": { "callouts": 0, "avg_peak_x": null, "median_peak_x": null, "best_peak_x": null, "sum_peak_x": 0.0, "hits": 0, "hit_rate": 0.0, "avg_now_x": null, "tracking": 0 },
      "1d": { "callouts": 1, "avg_peak_x": 1.42, "median_peak_x": 1.42, "best_peak_x": 1.42, "sum_peak_x": 1.42, "hits": 0, "hit_rate": 0.0, "avg_now_x": 1.1, "tracking": 1 },
      "7d": { "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, "avg_now_x": 1.0412, "tracking": 3 },
      "30d": { "callouts": 11, "avg_peak_x": 2.0127, "median_peak_x": 1.61, "best_peak_x": 4.48, "sum_peak_x": 22.1397, "hits": 4, "hit_rate": 36.36, "avg_now_x": 0.7215, "tracking": 5 }
    },
    "callouts_all_time": 23
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-11-03T09:41:02Z"
  }
}
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | external\_id (or csid\_id) is missing. |
| 400 | invalid\_parameter | hit\_x or csid\_id 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. |
| 404 | platform\_user\_not\_found | No platform user with this external\_id, and no user of your app with this csid\_id. |
| 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.