---
title: "List prediction-market events"
method: GET
path: "/v4/data/prediction/events"
tags: ["Prediction API"]
---

# List prediction-market events

`GET /v4/data/prediction/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).

## Query parameters

- `platform` 'polymarket' | 'kalshi' — Prediction-market platform identifier.
- `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.
- `category` string
- `tag` string
- `search` string
- `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.
- `cursor` string — 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.
- `limit` integer
- `includeMarkets` boolean

## Response `200`

OK

- PredictionEventsListResponse — Paginated list of prediction-market events.
  - `data` PredictionEvent[], required
    - `id` string, required — Platform-native event identifier (Polymarket numeric id or Kalshi event ticker).
    - `platform` 'polymarket' | 'kalshi', required — Prediction-market platform identifier.
    - `title` string, nullable, required — Event title.
    - `description` string, nullable, required — Long-form event description, when available.
    - `category` string, nullable, required — Event category label, when available.
    - `tags` string[], required — Free-form tag slugs. May be empty on Kalshi.
    - `imageUrl` string, nullable, required — Image / icon URL for the event, when available.
    - `status` string, required — Verbatim upstream status string. Richer than the `?status=` filter enum.
    - `openTime` string, date-time, nullable, required
    - `closeTime` string, date-time, nullable, required
    - `marketCount` integer, required — Number of markets attached to this event.
    - `totalVolume` number, required — Sum of nested-market volume, in `volumeUnit` units.
    - `volumeUnit` 'usd' | 'contracts', required — Unit for `volume` and `totalVolume` fields. `usd` on Polymarket (dollar-denominated notional); `contracts` on Kalshi (contract count — not USD).
    - `totalLiquidity` number, nullable, required — Sum of nested-market quoted liquidity. `null` on Kalshi events because the underlying market liquidity is not exposed there.
    - `markets` union[], required — The event's markets. **Never null.** - When the request passes `includeMarkets=true`, each entry is a full market object. - Otherwise (default, `includeMarkets=false`), each entry is a **market ID string**. The id is exactly what the get-market-by-id endpoint accepts — copy an id and call `GET /v4/data/prediction/markets/{id}` to fetch that market's full details.
      - union
        - string — Market ID — pass to `GET /v4/data/prediction/markets/{id}`.
        - PredictionEventMarket — Market row as nested inside an event. Same shape as the top-level `PredictionMarket` minus the `chain` block (which is only surfaced on the dedicated markets endpoints).
          - `id` string, required — Platform-native market identifier (Polymarket condition id or Kalshi market ticker).
          - `platform` 'polymarket' | 'kalshi', required — Prediction-market platform identifier.
          - `eventId` string, nullable, required — Parent event id. Polymarket numeric event id, or Kalshi event ticker. `null` when the upstream does not group this market under an event.
          - `question` string, required — Human-readable market question.
          - `description` string, nullable, required — Long-form description or resolution rules.
          - `category` string, nullable, required — Category label, when available.
          - `tags` string[], required — Free-form tag slugs. May be empty on Kalshi.
          - `imageUrl` string, nullable, required — Image / icon URL for the market, when available.
          - `status` string, required — Verbatim upstream status string. Richer than the `?status=` filter enum — values can include `paused`, `archived`, `settled`, `determined`, etc.
          - `openTime` string, date-time, nullable, required — ISO-8601 timestamp the market opened for trading.
          - `closeTime` string, date-time, nullable, required — ISO-8601 timestamp the market closes / closed for trading.
          - `settleTime` string, date-time, nullable, required — ISO-8601 timestamp the market is expected to settle.
          - `outcomes` PredictionMarketOutcome[], required — All outcomes of the market.
            - `name` string, required — Outcome label.
            - `price` number, required — Current probability in [0, 1].
            - `tokenId` string, nullable, required — Polymarket CTF token id for this outcome (numeric string). `null` on Kalshi — Kalshi outcomes are not tokenised.
          - `volume` number, required — Total volume in `volumeUnit` units.
          - `volumeUnit` 'usd' | 'contracts', required — Unit for `volume` and `totalVolume` fields. `usd` on Polymarket (dollar-denominated notional); `contracts` on Kalshi (contract count — not USD).
          - `liquidity` number, nullable, required — Quoted-resting-orders depth. `null` on Kalshi — the upstream markets feed does not populate this; aggregate orderbook depth client-side if you need it.
          - `resolution` PredictionMarketResolution, required — Resolution payload populated only after a market has settled. `null` on every active or paused market.
            - `outcome` string, required — Winning outcome name (matches one of the market's `outcomes[].name`).
            - `resolvedAt` string, date-time, required — ISO-8601 timestamp the market was resolved at.
            - `txHash` string, nullable, required — On-chain resolution transaction hash when available. `null` on Kalshi (the resolution is recorded off-chain on Kalshi's side).
            - `source` string, nullable, required — Resolution source attribution (e.g. `uma`, `kalshi`). `null` when the upstream does not expose it.
          - `createdAt` string, date-time, nullable, required — ISO-8601 timestamp the market was created upstream.
          - `source` PredictionMarketSource, required — Upstream platform attribution for a market or event row.
            - `platform` 'polymarket' | 'kalshi', required — Prediction-market platform identifier.
            - `platformId` string, required — Platform-native identifier. Polymarket condition id (0x + 64 hex) or numeric event id; Kalshi market or event ticker.
            - `url` string, required — Canonical public URL on the source platform.
    - `source` PredictionMarketSource, required — Upstream platform attribution for a market or event row.
      - `platform` 'polymarket' | 'kalshi', required — Prediction-market platform identifier.
      - `platformId` string, required — Platform-native identifier. Polymarket condition id (0x + 64 hex) or numeric event id; Kalshi market or event ticker.
      - `url` string, required — Canonical public URL on the source platform.
  - `pagination` PredictionCursorPagination, required — Cursor-based pagination wrapper. The `cursor` field is omitted on the last page; `pageSize` reflects the page size of the call that produced this response.
    - `cursor` string — 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.
    - `pageSize` integer, required — Page size of the page that produced this response.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
- `403` — Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.
- `500` — Internal server error. There was an error on the server during the processing of the request.

---

[API](https://skmtc.net/tatum/apis/blockchain-data.md) · [All operations](https://skmtc.net/tatum/apis/blockchain-data/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tatum/blockchain-data/versions/8622ee4b8fae/schema)