Get a token's price history
The price-history series for one outcome token, or a single point-in-time observation.
Three window forms, exactly one per request: start (with optional end),
interval, or as_of. Points are served oldest-first; pass ?cursor= from
a prior response’s next_cursor for the next page.
interval=max (or all) serves the market’s whole life, back to 2022 for
the oldest markets, at 12-hour buckets unless bucket_seconds says
otherwise; explicit start/end windows cap at 15 days, so the presets
are the long-range path.
The series ends with a terminal point: the latest observation inside the
window, which is a real tick and so can fall between bucket boundaries.
Nothing may assume uniform spacing (sparse data already forbids that), and
each point’s resolution_seconds says what window it was observed in.
Availability is graded by resolution. The 3-hour and 12-hour series are
permanent (back to 2022-11-18); the fine grains are windowed, with these
MINIMUMS: 1-minute data at least 7 days, 5-minute at least 60, 30-minute at
least 90. Floors, not exact horizons: data expires in multi-day chunks, so a
grain usually reaches a few days further back than its minimum. Coverage is
measured per request, never assumed from a table, so bucket_seconds=60
over a window starting a month ago is an incompatible pair: both values are
valid, and there is no data at their intersection.
The two ways of asking behave differently on purpose:
bucket_secondssent is served exactly as asked, so over a window whose resolution has expired you get an empty page rather than a silent substitution.bucket_secondsomitted lets the server choose a width that can actually serve the window: the finest tier grain whose series stays under ~2,500 points, except that a window wider than 12 hours never defaults to the 60-second grain (ask forbucket_seconds=60explicitly when you want it over a longer window), and coarsened further if that grain does not reach the window’s start. A window up to 12 hours keeps 1-minute detail (an hour 60 points, 12 hours 720); beyond that it moves to a materialized tier (a day 288, three days 864, a week 2,016, fifteen days 720). Sendbucket_secondswhen you want a specific density instead.
A RESOLVED market’s series ends with one settlement point: the on-chain
payout of the requested token (0 lost, 1 won, fractional for voided or
split resolutions) at resolution_seconds 0, placed one bucket edge past
the last stored row and clamped to an explicit window’s end. It appears
only on the final page of a paginated walk, and only once the resolution
is settled on-chain; an unresolved market’s series is unchanged.
resolution_seconds on every point reports what it was served at, so read it
instead of assuming the width a recent window would have given you. For a
multi-day window prefer a grain-aligned bucket_seconds (300, 1800, 10800,
43200) or omit it; a 60-second width over days is the one shape that is both
slow and, past 7 days, empty.
Query Parameters
Window start, epoch seconds, INCLUSIVE. Alone it means "up to the present", and is capped at 15 days back from now.
Pass end too when paging: a window that tracks the present keeps
growing at the tip, and the 15-day cap is re-checked on every page, so a
walk that starts near the cap can outlive it.
Relative window INSTEAD of start/end: max, all, 1m, 1w,
1d, 6h, 1h, matched case-sensitively. An empty interval= is a
malformed value, not an absent one.
max/all serve the market's WHOLE life (back to 2022 for the oldest
markets) at 12-hour buckets by default; at bucket_seconds of 10800 or
43200 the window is unbounded, while finer widths keep a 30-day window.
The other intervals take a width sized to their own span when
bucket_seconds is omitted (1h/6h/1d 60, 1w 300, 1m 1800), and
each still floors an explicit value: 600 for max/all/1m, 300 for
1w.
Bucket width in SECONDS (60…86400). bucketSeconds is an accepted alias.
OMIT it and the server sizes the width to the window: the finest tier
grain (60, 300, 1800, 10800, 43200) that keeps the series under ~2,500
points, except that an explicit window wider than 12 hours never
defaults to the 60s grain (send bucket_seconds=60 when you want
second-by-minute detail over a longer window), and coarsened further if
that grain no longer reaches the window's start.
So a window up to 12 hours keeps 1-minute detail, half a day through a
week defaults to 300, fifteen days to 1800; interval presets keep their
own span-derived defaults (1d 60s, 1w 300, 1m 1800, and the
unbounded max/all 43200).
SEND it and it is served exactly as asked, which for a window older than
that resolution's retention means an empty page rather than a silent
substitution. An explicit value is also floored per interval: 600 for
max/all/1m, 300 for 1w.
Response
A page of the price-history series
{ data, pagination } envelope for /v2/prices-history. The terminal
point (the latest observation inside the window) is part of the series
and lands on the final page, so a client that wants the freshest value
on a multi-page series follows the cursor to the end.