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

> Fire a webhook with holder counts and balances for specific positions as they change.

<Note>
  **Event:** `position_holder_metrics` \
  **Cost:** 0.025 credits per delivery
</Note>

Fires with updated holder metrics for the positions you subscribe to, including holder count, total balance, and total cost basis. The full payload schema is in the auto-generated [Position Holder Metrics callback](/api-reference/webhook-callbacks/position-holder-metrics-callback) reference; this page documents the filters and matching behavior.

## When to use this

* Track how many wallets hold a specific outcome token over time.
* Watch total balance and cost basis concentration on positions you care about.
* Detect accumulation or distribution as holder counts move on key positions.

## Subscription filters

Add these to the `filters` object when you create the subscription.

| Filter         | Type      | Required | Description                                          |
| -------------- | --------- | -------- | ---------------------------------------------------- |
| `position_ids` | string\[] | Yes      | Position token IDs to track (at least one, max 500). |

Unlike the optional filters on the PnL webhooks, `position_ids` is required: a subscription must name at least one position to receive deliveries.

## Example

```json theme={null}
{
  "url": "https://your-server.com/webhooks",
  "event": "position_holder_metrics",
  "filters": {
    "position_ids": [
      "71321045679252212594626385532706912750332728571942532289631379312455583992563"
    ]
  }
}
```

## Notes

* The payload is a `PositionHolderMetricsRow` with holder count, total balance, and total cost basis, plus the owning condition and event holder counts when available.
* Each subscription accepts up to 500 position IDs.