Point-in-time snapshots: the Polymarket snapshot-at API

• GET /v1/markets/{id_or_slug}/snapshot-at/{timestamp} returns nearest book + reference at or before the time
• Each token block carries bids, asks and a mid price, or nulls when a side is empty
• age_ms reports the milliseconds between the nearest book and the requested instant
• The reference block returns the nearest spot and TWAP observations for the asset

The response has three parts: the market detail, a snapshot block, and per-token books. The snapshot block sets the requested time, the actual nearest book time, and age_ms - the distance between them - plus a reference object with the nearest spot and TWAP prints.

The per-token block carries a Yes and a No entry, each with bids, asks and a mid price. When a side is empty the mid is null, which is the endpoint telling you the book was one-sided at that instant rather than inventing a price.

age_ms is the honesty field. If you ask for the exact expiry moment and the nearest stored book is 3,000 milliseconds away, age_ms is 3000 and you should treat the book as an approximation of that instant, not a fact about it.

For settlement analysis, set a tolerance. If age_ms is small - within a few hundred milliseconds - the snapshot is effectively the state at expiry. If it is large, either widen your search or fall back to a range query and interpolate deliberately.

The reference object returns the nearest spot and TWAP observations for the market's asset at or before the requested time. This is what lets you answer 'what reference level was live at expiry' in a single call, without a separate reference query.

When reference coverage does not reach back to the requested time - for example early in a newly added asset's capture - the nearest observation will be far away or absent, and the age in the reference rows makes that visible.

import requests

BASE = "https://api.polyorderbooks.com/v1"
HEADERS = {"X-API-Key": "your-key"}

# What did this BTC market look like at expiry?
slug = "btc-updown-5m-1787486400"
ts = 1787486700
r = requests.get(
    f"{BASE}/markets/{slug}/snapshot-at/{ts}",
    headers=HEADERS,
)
r.raise_for_status()
snap = r.json()["snapshot"]
print("age_ms:", snap["age_ms"])
for label, tok in snap["tokens"].items():
    print(label, "mid:", tok["price"], "levels:",
          len(tok["bids"]), len(tok["asks"]))

Reach for snapshot-at when you need one moment: the instant a market expired, the second a news headline landed, or the exact tick a strategy triggered. It is cheaper and clearer than pulling a range and scanning for the nearest row.

For anything you will repeat across thousands of markets, still prefer the range endpoints - they return many points per request - and use snapshot-at to spot-check or for the handful of moments where exactness matters.

const BASE = 'https://api.polyorderbooks.com/v1'
const headers = { 'X-API-Key': 'your-key' }

const slug = 'btc-updown-5m-1787486400'
const ts = 1787486700
const res = await fetch(`${BASE}/markets/${slug}/snapshot-at/${ts}`, { headers })
const { snapshot } = await res.json()
console.log('age_ms:', snapshot.age_ms)
console.log('reference twap:', snapshot.reference.twap?.value ?? 'none')
console.log('yes mid:', snapshot.tokens.Yes?.price ?? 'empty')

The Starter plan is free, includes order books, prices, and metrics at 250ms resolution, with 3 days of history, 60 requests/min, 1,000/day, 1 free AI backtest, and 3 strategy backtests. No credit card required.

Paid data windows from $19/mo extend history to 30–120 days at higher throughput. Backtest AI add-on is +$19/mo or standalone at $29/mo.

• Reference price snapshots
• Reference price coverage and gaps
• Order book, explained