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.

Resolution has a shelf life, so a window’s AGE decides what it can be served at. 1-minute data is kept 7 days, 5-minute 60 days, 30-minute 90 days; the 3-hour and 12-hour series are permanent (back to 2022-11-18). 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_seconds sent is served exactly as asked, so over a window whose resolution has expired you get an empty page rather than a silent substitution.
• bucket_seconds omitted lets the server choose a width that can actually serve the window: the finest tier grain whose series stays under ~2,500 points, coarsened further if that grain does not reach the window’s start. A window up to a day keeps 1-minute detail (an hour 60 points, a day 1,440); beyond that it moves to a materialized tier (three days 864, a week 2,016, fifteen days 720, a month 1,440). Send bucket_seconds when you want a specific density instead.

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.

GET /v2/prices-history

Get a token's price history

cURL

curl --request GET \
  --url https://data-api.polymarket.com/v2/prices-history \
  --header 'Authorization: Bearer <token>'

200

{
  "data": [
    {
      "price": 123,
      "resolution_seconds": 123,
      "timestamp": 123
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 1,
    "offset": 1,
    "next_cursor": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

token_id · string | null

Outcome token id (the CLOB asset id the chart is keyed by). Required. tokenId is an accepted alias.

start · integer<int64> | null

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.

end · integer<int64> | null

Window end, epoch seconds, EXCLUSIVE. Requires start; on its own it would ask for every point ever recorded up to end.

interval · string | null

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_seconds · integer<int64> | null

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, coarsened further if that grain no longer reaches the window's start. So a window up to a day keeps 1-minute detail, three days and a week default to 300, fifteen days and a month to 1800, and an unbounded max/all to 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.

as_of · integer<int64> | null

Point-in-time read, epoch seconds, INCLUSIVE: the latest observation at or before this instant. Cannot be combined with a window. asOf is an accepted alias.

limit · integer<int32> | null

First-page size; defaults to the cap (10,000). Ignored when cursor is supplied (the cursor's size wins).

Required range: 0 <= x <= 10000

cursor · string | null

Opaque pagination cursor from a prior response's next_cursor.

Response

200

application/json

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.

data · object[] · required

The page's rows.

Show child attributes

pagination · object · required

Paging envelope: follow next_cursor until null.

Show child attributes