Sign in

v1

latestOpenAPI 3.1.02026-07-243035381.4 MB
Prediction API

List prediction-market events

/v4/data/prediction/events

100 credits per API call

List prediction-market events across supported platforms. An event is a top-level grouping of one or more markets that share a common question or outcome set (e.g. "2028 US Presidential Election"). Each event row includes a roll-up of nested market counts, total volume, and total liquidity, with an opt-in to embed the full list of nested markets via includeMarkets=true.

Supported platforms (filter via platform or omit for a cross-platform feed):

  • Polymarket — polymarket
  • Kalshi — kalshi

Filtering, sorting and pagination

  • The status, category, tag and search filters are only honoured by Polymarket. To use any of them you must also pin platform=polymarket — calling them without that pin returns 400 so the response is honest about what was filtered.
  • sort accepts volume_desc, liquidity_desc, endingSoon, newest. When omitted on a cross-platform feed, results are interleaved so neither platform dominates the first page.
  • Pagination is cursor-based. The first call returns a pagination.cursor; pass that value verbatim as ?cursor=… on the next call. Cursors are opaque, fingerprint-bound to the filter set, and expire when filters change — never construct or modify them by hand. The cursor field is omitted from pagination on the last page.

Other notes

  • volumeUnit is usd on Polymarket events (dollar-denominated volume) and contracts on Kalshi events (number of contracts traded, not USD).
  • totalLiquidity is null on Kalshi — quoted liquidity is not exposed at the event level on Kalshi; compute from per-market orderbook depth if you need it.
  • status in the response is the verbatim upstream status string (richer than the status filter enum) — values can include paused, archived, settled, etc.
  • markets is populated only when includeMarkets=true is passed; otherwise it is null. When populated, every nested market is returned (no internal cap).
get/v4/data/prediction/events

Query parameters

platform'polymarket' | 'kalshi'

Prediction-market platform identifier.

Example:polymarket

Filter to a single platform. Omit for a cross-platform feed.

status'active' | 'closed' | 'resolved'

Coarse lifecycle filter used by the ?status= query parameter. The response field status carries a richer, platform-native string (e.g. paused, archived, settled); this enum is used only for filtering.

Example:active

Filter by lifecycle status. Polymarket-only — must be combined with platform=polymarket.

categorystring
Example:politics

Filter by event category. Polymarket-only — must be combined with platform=polymarket. Free-form string, max 64 characters.

tagstring
Example:us-elections

Filter by event tag slug. Polymarket-only — must be combined with platform=polymarket. Free-form string, max 64 characters.

searchstring
Example:election

Free-text search across event titles. Polymarket-only — must be combined with platform=polymarket. Max 256 characters.

sort'volume_desc' | 'liquidity_desc' | 'endingSoon' | 'newest'

Sort order for event and market listings. When omitted on a cross-platform feed, results are interleaved between platforms instead.

Example:volume_desc

Sort order. When omitted on a cross-platform feed, results are interleaved to balance the two platforms; otherwise sorted within the merged set.

cursorstring

Opaque base64-encoded pagination token. Returned in pagination.cursor on responses that have more pages. Pass back verbatim as ?cursor=… to fetch the next page. Cursors are fingerprint-bound to the filter set — modifying any filter between calls invalidates the cursor and returns 400. The field is omitted from pagination on the last page.

Example:eyJwbUV2dEN1cnNvciI6IjIwMjUtMTEtMDFUMTI6MzQ6NTZaIn0=

Opaque cursor returned by the previous response's pagination.cursor. Omit on the first call. Fingerprint-bound to the filter set — changing filters invalidates the cursor.

limitinteger
Example:20

Page size. Defaults to 20 when omitted.

includeMarketsboolean

When true, each event includes its full nested markets[] array. Defaults to false to keep list payloads light — opt in when you need per-event market depth.

Response

OK

Example response

{
  "data": [
    {
      "id": "KXELONMARS",
      "platform": "polymarket",
      "title": "Will Elon Musk land humans on Mars by 2030?",
      "description": "Outcome resolves on confirmation of a successful crewed Mars landing.",
      "category": "Science",
      "tags": [
        "space",
        "spacex"
      ],
      "imageUrl": "https://polymarket.com/images/elon-mars-event.png",
      "status": "active",
      "openTime": "2024-01-01T00:00:00Z",
      "closeTime": "2030-12-31T23:59:59Z",
      "marketCount": 3,
      "totalVolume": 4823100.5,
      "volumeUnit": "usd",
      "totalLiquidity": 271800.3,
      "markets": [
        "KXELONMARS-99"
      ],
      "source": {
        "platform": "polymarket",
        "platformId": "KXELONMARS-99",
        "url": "https://kalshi.com/markets/kxelonmars"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJwbUV2dEN1cnNvciI6IjIwMjUtMTEtMDFUMTI6MzQ6NTZaIn0=",
    "pageSize": 20
  }
}