---
title: "List Markets"
method: GET
path: "/api/v1/markets"
tags: ["markets"]
---

# List Markets

`GET /api/v1/markets`

## Request

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

Use when the user wants to browse, filter, or sort individual markets (not events). Returns paginated markets with their probability, volume, source, parent event ID, and 24h delta. Filterable by source, country, category, status, and full-text `search`. Sortable by `volume_24hr` or `probability`. Cap `page_size` ≤ 50 for chat-friendly responses.

## 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.
- `spread_min` number, nullable: Minimum bid-ask spread (0-1). Higher = less liquid.
- `spread_max` number, nullable: Maximum bid-ask spread (0-1). Lower = more liquid.
- `probability_min` number, nullable: Minimum probability (0-1). Filters to markets above this implied probability.
- `probability_max` number, nullable: Maximum probability (0-1).
- `prob_24h_change_min` number, nullable: Minimum 24h probability change (-1 to 1, signed). Use 0.15 for >=15pp positive moves.
- `prob_24h_change_max` number, nullable: Maximum 24h probability change (-1 to 1, signed).
- `volume_24h_change_min` number, nullable: Minimum 24h notional volume change (signed USD; e.g. 1000 means +$1k vs prior 24h).
- `volume_24h_change_max` number, nullable: Maximum 24h notional volume change (signed USD).
- `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

- PageMarketOut
  - `items` MarketOut[], required
    - `source` string, required: Venue the market comes from: polymarket, kalshi, manifold, myriad, limitless, predict, opinion or gemini.
    - `id` string, required: The venue's own market id; unique within `source`.
    - `event_id` string, nullable: Id of the parent event (same `source`). Null for orphan markets.
    - `slug` string, nullable: The venue's URL slug or ticker for the market, if any.
    - `question` string, nullable: The market's full question as the venue titles it. For outcomes of a multi-outcome event this can be a bare label (e.g. `Phoenix Suns`); pair it with `event_title`.
    - `group_item_title` string, nullable: Short outcome label for display under an already-shown event title, e.g. `Lakers` for 'Will the Lakers win the 2026 NBA Championship?'. Null when the venue supplies no separate label.
    - `description` string, nullable: Resolution rules / description text as published by the venue.
    - `image` string, nullable: Image URL published by the venue.
    - `icon` string, nullable: Icon URL published by the venue.
    - `outcomes` string[]: Outcome labels in venue order, usually `["Yes", "No"]`; other pairs exist (e.g. `["Over", "Under"]`, two team names).
    - `outcome_prices` number[]: Price of each outcome in `outcomes` order, in [0, 1] (0.62 = 62 cents on the dollar).
    - `probability` number, nullable: Implied probability of the first outcome (usually YES), in [0, 1]. The venue's own probability where it publishes one, else `outcome_prices[0]`.
    - `spread` number, nullable: Best ask minus best bid on the first outcome, in price units [0, 1]. Null when the venue publishes no order book.
    - `active` boolean, required: The venue's own active flag.
    - `closed` boolean, required: True once the venue has closed the market to trading (it may or may not have resolved yet; see `result`).
    - `start_date` string, date-time, nullable: When the market 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 market (UTC).
    - `result` string, nullable: Venue-reported resolution, as the venue wrote it: usually yes/no (case varies by venue), Kalshi `scalar`, Manifold `CANCEL`/`MKT`, or the winning outcome label for non-Yes/No pairs (e.g. `over 2.5`, `Over`, a team name). Polymarket publishes no result field; for it this is derived from its UMA resolution status `resolved` plus a settlement price >= 0.99. Null until the market resolves.
    - `volume` number, nullable: Lifetime trading 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. Null when the venue publishes no per-market volume (Gemini reports it per event); 0 means genuinely no trading.
    - `volume_24hr` number, nullable: Trading volume over the last 24 hours. 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. Limitless publishes no 24h figure, so pdata derives it from its own snapshots.
    - `prob_24h_change` number, nullable: Change in `probability` over the last 24 hours, as a fraction on the same [0, 1] scale (0.05 = up 5 percentage points; negative = fell): the current value minus the oldest snapshot recorded in the trailing 24h. Null when there is no price, no snapshot in that window, or the market closed >24h ago.
    - `volume_24h_change` number, nullable: Current `volume_24hr` minus the oldest snapshot of it recorded in the trailing 24h, in the same venue unit (positive = more activity than a day earlier). 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.
    - `categories` string[]: pdata topic categories of the parent event (e.g. Politics, Sports). Empty for orphan markets and uncategorised events.
    - `countries` string[]: Countries the market concerns, full English names (at most 3), assigned by pdata's AI tagging. Empty when none applies or not yet tagged.
    - `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 market.
    - `fetched_at` string, date-time, required: When pdata last fetched this row from the venue (UTC).
    - `added_at` string, date-time, nullable: When this market first appeared in pdata's database (UTC). Null for markets loaded with pdata's initial backfill, whose real first appearance is earlier.
    - `url` string, nullable: Public page for this market on the venue's own website. Null when the venue's URL pattern needs data this row lacks.
    - `event_title` string, nullable: Title of the parent event. Use it with `question` when the question is only an outcome label. Null for orphan markets.
    - `chart_24h` number[], nullable: Last-24h `probability` series in [0, 1], oldest first, at most 50 points. Null when fewer than 2 snapshots exist in the window.
  - `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)