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

> Fire a webhook when a position's metrics cross your thresholds within a timeframe.

<Note>
  **Event:** `position_metrics` \
  **Cost:** 0.1 credits per delivery
</Note>

The `position_metrics` callback fires when a position's (outcome token's) metrics cross your thresholds within a timeframe. The full payload schema is in the auto-generated [Position Metrics callback](/api-reference/webhook-callbacks/position-metrics-callback) reference; this page documents the filters and matching behavior.

<Note>
  **`price_*` and `probability_*` are different series.** `price_*` tracks the outcome token you're looking at (filter: `min_price_change_pct`); `probability_*` always tracks the Yes/Up token, index `0` (filter: `min_probability_change_pct`). They agree on the Yes side; on the No side they are complements (a `price` of `0.40` is a `probability` of `0.60`).
</Note>

## When to use this

* Catch outcome tokens with surging buy- or sell-side volume inside a rolling window.
* Alert on sharp price or probability moves on specific positions.
* Monitor fee accrual, transaction count, or unique-trader growth at the outcome-token level.

## Subscription filters

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

| Filter                       | Type      | Description                                                                         |
| ---------------------------- | --------- | ----------------------------------------------------------------------------------- |
| `position_ids`               | string\[] | Restrict to specific outcome tokens by position ID (max 500).                       |
| `condition_ids`              | string\[] | Restrict to specific markets by condition ID (max 500).                             |
| `outcomes`                   | string\[] | Restrict by outcome name, e.g. `["Yes", "No"]` (max 500).                           |
| `min_volume_usd`             | number    | Minimum traded volume in USD.                                                       |
| `max_volume_usd`             | number    | Maximum traded volume in USD.                                                       |
| `min_buy_usd`                | number    | Minimum buy-side volume in USD.                                                     |
| `min_sell_volume_usd`        | number    | Minimum sell-side volume in USD.                                                    |
| `min_fees`                   | number    | Minimum fees accrued in USD.                                                        |
| `min_txns`                   | integer   | Minimum transaction count.                                                          |
| `min_unique_traders`         | integer   | Minimum number of unique traders.                                                   |
| `min_price_change_pct`       | number    | Minimum price change, as a percentage.                                              |
| `min_probability_change_pct` | number    | Minimum probability change, as a percentage.                                        |
| `timeframes`                 | string\[] | One or more windows: `1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`, `lifetime`. |

## Example

```json theme={null}
{
  "url": "https://your-server.com/webhooks",
  "event": "position_metrics",
  "filters": {
    "outcomes": ["Yes"],
    "min_buy_usd": 10000,
    "min_price_change_pct": 5,
    "timeframes": ["1h"]
  }
}
```

## Notes

* `timeframes` selects which rolling windows are evaluated; the event fires when the thresholds are met in any listed window.
* `min_price_change_pct` and `min_probability_change_pct` are measured over the evaluated window.