HOW ALERTS WORK
How a Pinnacle API odds drop becomes an alert.
A Pinnacle price falls in the odds API, and a rule decides whether you hear about it. Percentage threshold, time window, sport filter, delivery: this is what happens between the move and the alert your application receives.
What counts as a drop in the Pinnacle odds API
A drop is a percentage fall inside a rolling time window. Two prices define every move: the old price, where the selection traded at the start of the window, and the new price, where it trades now.
Drop = (old − new) ÷ old × 100. A home win that moves from 2.10 to 1.95 has dropped 7.1%. The percentage form keeps the rule honest across the board: the same 0.15 fall is 10% on a 1.50 favourite and only 1.4% on an 11.00 longshot. Absolute ticks would treat those moves as equal; your rule should not.
The feed's engine runs this test inside its own detection window and
pushes every fall at or above your min_drop threshold, from 1%
up. The engine's window is set by the service; a longer window, like the
ones below, is a rule you run on the alerts you receive.
A window of your own should roll rather than reset. There are no candles and no fixed intervals: with a ten-minute window, each incoming price is tested against the price from ten minutes earlier, not against the top of the hour.
Choosing thresholds and windows
Worked example: a rule of 5% within 10 minutes. A selection drifts from 2.40 to 2.28 over nine minutes, which is (2.40 − 2.28) ÷ 2.40 = 5.0%, and the alert fires. Spread the same move across 25 minutes and nothing fires: the window is as much a part of the rule as the percentage.
The tradeoff is sensitivity against noise. Lower thresholds and shorter windows fire more often: you catch moves early, and you also catch single-tick jitter in thin markets. Higher thresholds and longer windows surface fewer, more deliberate repricings. Both are valid; they answer different questions.
A practical starting point is wider than instinct suggests. Begin at 5% within 10 minutes on prematch markets, log every would-be alert for a week, then tighten the rule where the log shows noise. Your sport mix decides what is loud and what is quiet.
Filtering by sport and phase
Thresholds alone are not enough, because sports do not move alike. A tennis
match in play reprices on every point while a soccer outright drifts for
days. Filter before the rule runs: sport, league and phase are the usual
first cuts, and they keep irrelevant volume away from your threshold logic.
The stream has no sport parameter, so that filter lives in your code, on
each alert's sport or sport_id. Phase is split for
you: live and prematch drops arrive on separate streams.
Phase matters most. Most applications run live and prematch as separate rules with separate thresholds, because move size and cadence differ so much between the two. See live vs prematch drops for what changes between the rhythms.
To see what a threshold means in probability rather than price, the dropping odds calculator on pnclDATA turns any two prices into the shift the market made.
What an alert event carries
Each alert is self-contained. It names the line with sport,
league, sect (the market, such as Moneyline),
outcome and period, carries the price before and
after the fall as from_price and to_price, adds
nvp, the no-vig fair price after the move, and stamps the
alert time in Unix seconds as alerted. Build your dedupe key
from id, sect, outcome,
period and alerted together.
That is enough to route, dedupe and render an alert without a second request. When a decision needs the wider board, pair the stream with REST snapshots. Frame format, reconnects and parsing are covered in the SSE setup guide.
From alert to action
The alert is an input, not a betting signal. Routing it into a notification, a model trigger or a monitoring screen is your code's job; the stream's job ends at delivering clean events.
Before you connect anything, dry-run your rule on paper against recent price moves and see how a signal flows through receive, filter, act. When the rule holds up on paper, the drop stream delivers the events it runs on.