---
title: "List Events"
method: GET
path: "/api/v1/events"
tags: ["events"]
---

# List Events

`GET /api/v1/events`

## Request

- Base URL: `https://api.pdata.world`
- URL: `https://api.pdata.world/api/v1/events`
- Auth: none declared

Use when an agent wants to browse, filter, or search prediction-market events across all 8 platforms. Returns paginated events with their child markets, prices, and platform metadata. Filterable by source (polymarket/kalshi/manifold/myriad/limitless/predict/opinion/gemini), category, country, status (open/closed), and full-text search via `search`. Sortable by `volume_24hr`, `normalized_vol_24hr`, `liquidity`, `end_date`, or `closed_time` (prefix `-` for descending). Cap `page_size` ≤ 50 to keep responses small enough for LLM context windows.

## Query parameters

- `page` integer: Page number (1-indexed).
- `page_size` integer: Items per page (1-200; default 50). Pass page_size=5 for chat-style summaries.
- `source` string, nullable: Source name(s); single value or comma-separated list. Allowed: polymarket, kalshi, manifold, myriad, limitless, predict, opinion, gemini.
- `active` boolean, nullable: Filter by `active` flag (true/false).
- `closed` boolean, nullable: Filter by `closed` flag (true/false). Open markets are `closed=false`.
- `volume_24hr_min` number, nullable: Minimum 24h notional volume (USD). Excludes low-activity markets.
- `volume_24hr_max` number, nullable: Maximum 24h notional volume (USD).
- `volume_min` number, nullable: Minimum cumulative volume (USD). Excludes low-activity markets across full history.
- `volume_max` number, nullable: Maximum cumulative volume (USD).
- `rank_min` number, nullable: Minimum rank score (numeric). Higher = more prominent.
- `rank_max` number, nullable: Maximum rank score (numeric).
- `ends_after` string, date-time, nullable: Filter to events whose end_date >= this ISO 8601 datetime (e.g. `2026-06-01T00:00:00Z`).
- `ends_before` string, date-time, nullable: Filter to events whose end_date <= this ISO 8601 datetime.
- `hide_ended` boolean: If true, hide markets/events whose end_date is in the past (end_date <= now()); rows with no end_date are kept.
- `created_after` string, date-time, nullable: Filter to rows whose created_at >= this ISO 8601 datetime (first appearance in pdata's database).
- `created_before` string, date-time, nullable: Filter to rows whose created_at <= this ISO 8601 datetime.
- `status` string, nullable: Comma-separated status list; any of {open, closing-soon, resolved}
- `search` string, nullable: Full-text search across title, description, slug. Case-insensitive substring match.
- `sort` string, nullable: Field name; prefix '-' for descending order (e.g. `-volume_24hr`). Common allowed values: `volume_24hr`, `normalized_vol_24hr`, `liquidity`, `end_date`, `closed_time`, `updated_at`. Markets endpoints additionally accept `probability`, `prob_24h_change`, `spread`. Invalid values return 400.
- `categories` string, nullable: Comma-separated category labels to include (OR)
- `categories_exclude` string, nullable: Comma-separated category labels to exclude
- `hide_price_derivatives` boolean: If true, exclude events with is_price_derivative=TRUE
- `include_uncategorized` boolean: If true, the include clause also matches rows whose categories array is empty/NULL or contains only labels outside the canonical set (synthetic 'Other' bucket).
- `countries` string, nullable: Comma-separated country names to include (OR). Full English names per the AI categorizer's prompt — e.g. 'United States', 'United Kingdom', 'European Union'. No allow-list — misspelled values silently yield zero matches.
- `countries_exclude` string, nullable: Comma-separated country names to exclude.
- `include_uncountried` boolean: If true, the include clause also matches rows whose countries array is empty/NULL — country-agnostic markets (synthetic 'No country' bucket).
- `country_match` string: How multiple `countries` combine: 'any' (default, OR — tagged with any selected country) or 'all' (AND — tagged with all of them, e.g. both Iran and Israel). Markets carry ≤3 country tags.

## Response `200`

Successful Response

- PageEventOut
  - `items` EventOut[], required
    - `source` string, required: Venue the event comes from: polymarket, kalshi, manifold, myriad, limitless, predict, opinion or gemini.
    - `id` string, required: The venue's own event id; unique within `source`. pdata's page for it is https://pdata.world/events/{source}/{id}.
    - `ticker` string, nullable: The venue's event ticker (Kalshi), if any.
    - `slug` string, nullable: The venue's URL slug for the event, if any.
    - `title` string, nullable: Event title as the venue publishes it.
    - `description` string, nullable: Event description or resolution rules as published by the venue.
    - `image` string, nullable: Image URL published by the venue.
    - `icon` string, nullable: Icon URL published by the venue.
    - `active` boolean, required: The venue's own active flag.
    - `closed` boolean, required: True once the venue has closed the event; its markets carry the result.
    - `start_date` string, date-time, nullable: When the event opened, as the venue reports it (UTC).
    - `end_date` string, date-time, nullable: Scheduled close or expiry, as the venue reports it (UTC).
    - `closed_time` string, date-time, nullable: When the venue actually closed the event (UTC).
    - `volume` number, nullable: Lifetime trading volume of the event: the venue's event total, or the sum of its markets where the venue publishes none (Kalshi). Venue-reported, in the venue's own unit and not converted across venues: shares for Polymarket and contracts for Kalshi (each pays $1 at resolution), play-money mana for Manifold, and each other venue's figure as it reports it. Null when there is no volume signal.
    - `volume_24hr` number, nullable: Event trading volume over the last 24 hours, totalled the same way as `volume`. Venue-reported, in the venue's own unit and not converted across venues: shares for Polymarket and contracts for Kalshi (each pays $1 at resolution), play-money mana for Manifold, and each other venue's figure as it reports it.
    - `volume_24h_change` number, nullable: Current `volume_24hr` minus the oldest snapshot of it recorded in the trailing 24h, in the same venue unit. Null when there is no usable history.
    - `normalized_vol_24hr` number, nullable: `volume_24hr` on a 0-100 log scale within its venue. Computed as 100 x ln(v+1)^2 / ln(cap+1)^2, where cap is the venue's largest value (its second largest when the largest is over 5x it), so it compares magnitude across venues where raw volume units do not. Null when the input is null or 0.
    - `normalized_volume` number, nullable: Lifetime `volume` on a 0-100 log scale within its venue. Computed as 100 x ln(v+1)^2 / ln(cap+1)^2, where cap is the venue's largest value (its second largest when the largest is over 5x it), so it compares magnitude across venues where raw volume units do not. Null when the input is null or 0.
    - `liquidity` number, nullable: Liquidity as the venue reports it, in the venue's own unit.
    - `open_interest` number, nullable: Open interest as the venue reports it, in the venue's own unit (contracts for Kalshi, summed over the event's markets).
    - `categories` string[]: pdata topic categories (e.g. Politics, Sports), assigned by rules and AI tagging. Empty when uncategorised.
    - `tags` union[]: The venue's own tags, passed through as published: objects with id/slug/label for Polymarket, plain strings elsewhere.
      - union
        - string
        - object
    - `synthetic` boolean: True when pdata created this event to wrap a single market that has no event at the venue. It has exactly one market.
    - `is_group` boolean: True when pdata created this event to group sibling Kalshi events that share a matchup and end date. Its id, title and volumes are derived from its child events.
    - `group_key` string, nullable: Matchup key used to build group events (Kalshi). Null elsewhere.
    - `parent_event_id` string, nullable: Id of the pdata group event this event belongs to. Null for top-level events.
    - `probability` number, nullable: Probability in [0, 1], copied from the single market. Set only on synthetic events; real events have one probability per market.
    - `spread` number, nullable: Best ask minus best bid in price units [0, 1], copied from the single market. Set only on synthetic events.
    - `top_outcome` string, nullable: Label of the leading market: the highest-probability open market, or the highest-probability closed one when none is open. For independent (not mutually exclusive) markets this is the highest-priced, not a winner. Null when the event has no direct markets (group events).
    - `top_outcome_probability` number, nullable: Probability of `top_outcome`, in [0, 1]. Null when `top_outcome` or its price is null.
    - `top_outcome_prob_24h_change` number, nullable: 24-hour change in `top_outcome_probability`, as a fraction on the [0, 1] scale (0.05 = up 5 percentage points). Null without usable history.
    - `top_outcome_volume_24h_change` number, nullable: 24-hour change in the leading market's `volume_24hr`, in the venue's unit. Null without usable history.
    - `updated_at` string, date-time, required: When pdata last wrote this row (UTC): on every fetch from the venue, and again when pdata recomputes a derived field such as 24h volume, so it can be later than `fetched_at`. It is not when the venue last changed the event.
    - `fetched_at` string, date-time, required: When pdata last fetched this row from the venue (UTC).
    - `added_at` string, date-time, nullable: When this event first appeared in pdata's database (UTC). Null for events loaded with pdata's initial backfill, whose real first appearance is earlier.
    - `url` string, nullable: Public page for this event on the venue's own website. Null for venues without event pages (Myriad) or when required fields are missing.
    - `chart_24h` number[], nullable: Last-24h sparkline, oldest first, at most 50 points: the event's `volume_24hr` series for real and group events, or the single market's probability in [0, 1] for synthetic events. Null with fewer than 2 points.
  - `meta` PageMeta, required
    - `page` integer, required
    - `page_size` integer, required
    - `total` integer, required
    - `total_pages` integer, required
  - `_meta` ResponseMetaList, required: Agent metadata for list/aggregate responses (no cite_as).
    - `attribution` string: Who aggregated this data, under which licence, and whose data it is.
    - `canonical_url` string, required: Stable URL for this resource: the pdata.world page, or the API URL for list responses.
    - `as_of` string, date-time: When this response was generated (UTC).
    - `docs` string: API documentation.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/pdata/apis/pdata-backend.md) · [All operations](https://skmtc.dev/pdata/apis/pdata-backend/llms.txt) · [OpenAPI document](https://skmtc.dev/pdata/apis/pdata-backend/revisions/4c9bf3856786?raw)