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

# Position Holder Metrics

> Get notified when holder metrics update for a position.

<Note>
  **Event:** `position_holder_metrics` \
  **Endpoint:** `wss://api.struct.to/ws/alerts` \
  **Cost:** 0.025 credits per event
</Note>

Fires when holder metrics update for one of the positions you subscribe to, reporting the current holder count along with the aggregate balance and cost basis across all holders. The `position_ids` filter is required: you only receive metrics for the position token IDs you name.

## Filters

| Filter         | Type       | Required | Description                           |
| -------------- | ---------- | -------- | ------------------------------------- |
| `position_ids` | `string[]` | Yes      | Position token IDs to track (max 500) |

## Subscribe

```json theme={null}
{
  "op": "subscribe",
  "event": "position_holder_metrics",
  "position_ids": ["21742633143463906290569050155826241533067272736897614950488156847949938836455"]
}
```

## Response

```json theme={null}
{
  "event": "position_holder_metrics",
  "timestamp": 1775913505260,
  "data": {
    "ts": 1713052800,
    "block": 68554321,
    "position_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
    "holder_count": 1842,
    "total_balance": 5230000.0,
    "total_cost_basis": 2870000.00,
    "condition_holder_count": 3050,
    "event_holder_count": 9120
  }
}
```