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

> Fire a webhook when a position's volume surges past its recent baseline.

<Note>
  **Event:** `position_volume_spike` \
  **Cost:** 0.2 credits per delivery
</Note>

The `position_volume_spike` event fires when a position's volume in a timeframe exceeds its recent baseline by your spike ratio. The full payload schema is in the auto-generated [Position Volume Spike callback](/api-reference/webhook-callbacks/position-volume-spike-callback) reference; this page documents the filters and matching behavior.

## When to use this

* Detect activity surges on a single outcome token rather than a whole market.
* Tune sensitivity by setting how far volume must exceed its baseline.
* Scope alerts to specific outcomes or markets you track.

## Subscription filters

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

| Filter          | Type      | Description                                                                               |
| --------------- | --------- | ----------------------------------------------------------------------------------------- |
| `spike_ratio`   | number    | Volume must exceed its baseline by at least this ratio (must be greater than `1.0`).      |
| `window_secs`   | integer   | Look-back window in seconds (`1`–`600`).                                                  |
| `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).                                 |
| `timeframes`    | string\[] | One or more windows: `1m`, `5m`, `30m`, `1h`, `6h`, `1d`, `24h`, `7d`, `30d`, `lifetime`. |

## Example

```json theme={null}
{
  "url": "https://your-server.com/webhooks",
  "event": "position_volume_spike",
  "filters": {
    "spike_ratio": 4.0,
    "window_secs": 180,
    "outcomes": ["Yes"],
    "timeframes": ["1h"]
  }
}
```

## Notes

* `spike_ratio` must be greater than `1.0`; for example `3.0` means 3x the recent baseline.