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

# Price Threshold

> Fire a webhook when an outcome's price crosses a target level.

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

The `price_threshold` event fires when an outcome's price (implied probability) crosses a target level you set. It is edge-triggered: it fires once on the crossing, not on every trade that stays past the level. The full payload schema is in the auto-generated [Price Threshold callback](/api-reference/webhook-callbacks/price-threshold-callback) reference; this page documents the filters and matching behavior.

<Note>
  **`price` and `probability` are not the same field:**

  * **`price`**: the outcome you are looking at (the token in `outcome_index` / `position_id`).
  * **`probability`**: always outcome index `0` (the Yes/Up token), no matter which outcome the payload is about.

  They are equal only when `outcome_index` is `0`. On the No side (index `1`) they are complements: a `price` of `0.40` pairs with a `probability` of `0.60`.
</Note>

## When to use this

* Alert the moment an outcome crosses up through a level (e.g. YES reaches 75%) or down through one (e.g. YES falls to 25%).
* Build one-time triggers that delete themselves after firing, with [`one_shot`](/webhooks/fire-and-delete).
* Catch positions that are already past your target when you subscribe, with `fire_if_already_past`.

## Defining the threshold

Set `min_price` for an **upward** target (fire when the price crosses up to ≥ that value) and `max_price` for a **downward** target (fire when the price crosses down to ≤ that value). At least one is required; set both to watch a position from either side.

By default the event waits for a real crossing: it needs a prior observation on the other side of the target before it fires. Set `fire_if_already_past` to fire immediately when the first observed price is already past the target.

## Subscription filters

Add these to the `filters` object when you create the subscription. At least one of `min_price` or `max_price` is required.

| Filter                      | Type      | Description                                                                                                                                                       |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `min_price`                 | number    | Upward target, `0.0`–`1.0`. Fire when the price crosses up to ≥ this value (e.g. `0.75`).                                                                         |
| `max_price`                 | number    | Downward target, `0.0`–`1.0`. Fire when the price crosses down to ≤ this value (e.g. `0.25`).                                                                     |
| `one_shot`                  | boolean   | Delete the subscription after its first delivery ([fire-and-delete](/webhooks/fire-and-delete)). Requires `position_ids` or `condition_ids`. Defaults to `false`. |
| `fire_if_already_past`      | boolean   | Fire immediately if the first observed price is already past the target, with no prior baseline. Defaults to `false`.                                             |
| `condition_ids`             | string\[] | Restrict to specific markets by condition ID (max 500).                                                                                                           |
| `position_ids`              | string\[] | Restrict to specific outcome tokens by position ID (max 500).                                                                                                     |
| `outcomes`                  | string\[] | Restrict by outcome name, e.g. `["Yes", "No"]` (max 500). Note that multiple choice and esports markets often have non-standard outcome names (e.g. team names).  |
| `position_outcome_indices`  | number\[] | Restrict by outcome index: `0` (Yes/Up) or `1` (No).                                                                                                              |
| `event_slugs`               | string\[] | Restrict to specific events by slug (max 500).                                                                                                                    |
| `tags`                      | string\[] | Restrict to markets carrying any of these tags or category names, case-insensitive (max 500).                                                                     |
| `series_slugs`              | string\[] | Restrict to markets in any of these series by slug, case-insensitive (max 500).                                                                                   |
| `exclude_shortterm_markets` | boolean   | Exclude short-term Up/Down markets.                                                                                                                               |

<Tip>
  **Scope by market taxonomy.** `tags` matches a market's own tags **or** its category, given as the display label shown on Polymarket (for example `"Sports"`, `"Politics"`, or `"FIFA World Cup"`), not a slug. `series_slugs` matches the market's parent series by slug (for example `"nba-finals"`). Both are case-insensitive, accept up to 500 values each, and an empty or omitted list applies no taxonomy restriction.
</Tip>

## Example

Fire once when a specific market's YES outcome crosses up through 75%, then delete the subscription:

```json theme={null}
{
  "url": "https://your-server.com/webhooks",
  "event": "price_threshold",
  "filters": {
    "condition_ids": ["0x4fec624c0ff2bfae89956cebd6fbc9c58f995f824382dc587dc5a32a4b15940b"],
    "min_price": 0.75,
    "one_shot": true
  }
}
```

## Notes

* The event is edge-triggered: it fires on the transition past the target, then re-arms once the price moves back to the other side (unless `one_shot` deleted the subscription).
* The payload reports the crossing `direction` (`"up"` or `"down"`), the `threshold` that was crossed, and `previous_price` (the baseline the crossing was measured from).
* `one_shot` requires `position_ids` or `condition_ids` so the subscription targets a bounded set of markets.