Polling for fewer tokens

Why a wide call rarely gets a 304

The ETag labels the whole reply. A reply as wide as all of football holds every bookmaker's prices on every match, and a change to any one of them changes the label. Your next call is then a full 200, at the full price.

In the default envelope, meta also carries the reply's time, processed_at, which changes with each new version of the data. So an envelope's label moves even when none of your prices did.

Name only what you use

On standard, dutching and raw, each sport, bookmaker, exchange or market you name carries points, and the price is multiplied by the named points over 100, never above 1. Football is 54 points, so sports=soccer pays 54% of standard's 10,000 tokens. A competition key prices as its whole sport: sports=soccer_english_premier_league costs what sports=soccer costs.

One call to standard, from the 2026-09 price table:

• All of standard: 10,000 tokens. /v2/odds/standard?region=uk
• Football: 5,400 tokens. /v2/odds/standard?region=uk&sports=soccer
• Football, match odds only: 1,107 tokens. /v2/odds/standard?region=uk&sports=soccer&markets=h2h
• Football at three bookmakers: 292 tokens. /v2/odds/standard?region=uk&sports=soccer&bookmakers=ladbrokes,william_hill,paddy_power
• Football at one bookmaker: 184 tokens. /v2/odds/standard?region=uk&sports=soccer&bookmakers=ladbrokes

Send the ETag back

Keep the ETag from each 200 and send it back as If-None-Match. When the reply would be the same, you get 304 Not Modified, with no body and no tokens. Polling with ETags covers the rest of the 304.

In the envelope the label moves with every new version of the data, so ask for format=bare. The reply is then the events alone, and its time is still in the X-Processed-At header. Bare leaves out meta.last_seen; keyed /v2/coverage carries the same times.

With bare, the label changes only when your events do, so a narrower call gets more 304s. The four smaller products cost the same whatever you filter: with format=bare, a filter only makes a 304 likelier. The example client in the quickstart shows the If-None-Match step in three languages.

Quote a call before you loop it

Add quote=true to any data request and it returns the price instead of the odds, free. Price each new set of filters once, before it goes in a loop.

Follow raw with updatedSince

On raw, one price covers the whole walk and each page pays its share. To follow changes, walk again with updatedSince set to the start of your previous walk. An updatedSince no more than 120 s back pays 10% of the price. An older one pays the full price, however few events come back. A reply with no events is free.

Football on raw is 25,800 tokens a walk. A follow-up walk with a recent updatedSince is 2,580, plus up to a token a page from rounding. Paging through raw odds covers the cursor.