---
title: "List Movers"
method: GET
path: "/api/v1/news/movers"
tags: ["news"]
---

# List Movers

`GET /api/v1/news/movers`

## Request

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

Use when the user wants to see the news-feed view: markets that exhibited a probability spike in the chosen lookback window, scored by `|Δprob_pp| × log10(1+USD-equivalent volume)`. Refreshed after each Polymarket ingest cycle, typically every 15-20 min. The `window=` param selects the lookback: 24 (default, ≥15pp), 12 (≥12pp), or 2 (≥2h, ≥10pp); `prob_change` is measured over that window. Includes a `prob_history` array (24h bucketed trajectory) per row regardless of window. Filterable by `source=` and `categories=` (CSV). Soft flags (`is_entertainment`/`is_microprediction`/`is_crypto`/`is_sports`/`is_weather`) default OFF; opt in with `include_*=true`.

## Query parameters

- `source` string, nullable: Platform ID(s); single value or comma-separated list. Allowed: polymarket, kalshi, manifold, myriad, limitless, predict, opinion, gemini.
- `categories` string, nullable: Category filter (CSV). Examples: 'Politics', 'Sports', 'Crypto', 'Weather'. Maps to events.categories assignments.
- `q` string, nullable: Full-text search across market title and event title. Case-insensitive substring match.
- `min_score` number, nullable: Minimum spike score. Higher = more notable spikes only.
- `include_entertainment` boolean: Include entertainment markets (default: excluded for signal-to-noise).
- `include_microprediction` boolean: Include microprediction / hyperlocal markets (default: excluded).
- `include_crypto` boolean: Include crypto price-derivative markets (default: excluded).
- `include_sports` boolean: Include sports markets (default: excluded).
- `include_weather` boolean: Include weather markets (default: excluded).
- `include_resolved` boolean: Include resolved (closed) markets (default: excluded — news movers focus on live markets).
- `ordering` string: Sort order. Allowed values: `vol` (volume-weighted score; default), `score` (raw spike score), `prob` (probability change magnitude).
- `window` 2 | 12 | 24: Lookback windows the carousel selector exposes (hours). An IntEnum (not Literal[2,12,24]) because FastAPI coerces a query STRING to an IntEnum member but NOT to an int literal — `?window=24` would 422 against a Literal even though the Python default 24 validates.
- `page` integer: Page number (1-indexed).
- `page_size` integer: Items per page (1-200; default 50).

## Response `200`

Successful Response

- NewsMoversResponse: Response for GET /api/v1/news/movers.
  - `count` integer, required
  - `page` integer, required
  - `page_size` integer, required
  - `last_refreshed_at` string, date-time, nullable, required
  - `results` union[], required
    - union
      - NewsCluster: A cluster of news events that share a specific topical tag. Built per-source from the parent event's `tags` array (currently Polymarket-only — other sources don't reliably populate tags). Picked tag is the rarest globally that's also shared by at least two events in the news feed; the cluster's `cluster_label` is that tag's `label` field as published by Polymarket. `events` is the member event list sorted by score desc. The FE renders the cluster as a 3-level structure: cluster header → up to N events → each event's gainer/loser.
        - `kind` 'cluster'
        - `cluster_key` string, required
        - `cluster_label` string, required
        - `cluster_slug` string, required
        - `source` string, required
        - `src` 'pm' | 'ka' | 'ma' | 'li' | 'op' | 'pr' | 'my' | 'gm', required
        - `total_vol_24hr` number, required
        - `score` number, required
        - `events` NewsEventOut[], required
          - `kind` 'event': Row type: "event" (this shape) or "cluster" (a topic group of events).
          - `source` string, required: Venue: polymarket, kalshi, manifold, myriad, limitless, predict, opinion or gemini.
          - `market_id` string, required: The venue's market id (markets.id).
          - `src` 'pm' | 'ka' | 'ma' | 'li' | 'op' | 'pr' | 'my' | 'gm', required: Two-letter venue code used by the website.
          - `event_id` string, nullable: Parent event id; pdata's page is https://pdata.world/events/{source}/{event_id}. Null for orphan markets.
          - `question` string, nullable: The market's question as the venue titles it.
          - `group_item_title` string, nullable: Short outcome label within a multi-outcome event.
          - `event_title` string, nullable: Title of the parent event.
          - `cat` string, nullable: Primary pdata category of the row.
          - `categories` string[]: All pdata categories of the parent event.
          - `countries` string[]: Countries the market concerns, full English names, from pdata's AI tagging.
          - `prob` number, required: Current probability on a 0-100 scale (percentage points, e.g. 99.6) — news movers only; /events and /markets use [0, 1].
          - `d_prob` number, required: Signed change in percentage points: current `prob` minus the probability ~24h ago (the latest snapshot at or before then, else the oldest available). A row qualifies on any intra-day swing of 15+ points, so this can be small when the price went up and came back.
          - `vol_24hr` number, required: The market's venue-reported 24h volume, in the venue's own unit (shares for Polymarket, contracts for Kalshi, mana for Manifold).
          - `normalized_vol` number, required: `vol_24hr` on a 0-100 log scale within its venue (the market's `normalized_vol_24hr`); comparable across venues.
          - `end_date` string, date-time, nullable: Scheduled close, as the venue reports it (UTC).
          - `closed_time` string, date-time, nullable: When the venue closed the market (UTC).
          - `status` 'open' | 'closing-soon' | 'resolved', required: open, closing-soon (ends within 36 hours, or end date passed but not yet closed) or resolved (closed by the venue).
          - `is_resolved` boolean, required: True when `status` is resolved.
          - `url` string, nullable: The market's page on the venue's own website.
          - `event_url` string, nullable: The parent event's page on the venue's own website.
          - `image` string, nullable: Market image URL published by the venue.
          - `event_image` string, nullable: Parent event image URL published by the venue.
          - `spike_kind` 'prob': What moved. Always "prob" (probability).
          - `score` number, required: Ranking score: |d_prob| x log10(1 + 24h volume in USD terms), with Manifold mana counted at 0.01 USD. Higher ranks first.
          - `prob_history` number[]: 24 hourly probabilities on the 0-100 scale, oldest first (index 0 = 24h ago, 23 = now); null for hours with no snapshot. Empty when there is no history.
          - `spike` NewsSpike: The news-qualifying probability swing, pinned for the chart. The hourly ``prob_history`` can bucket a sub-hour spike away; this carries the actual peak snapshot so the carousel chart draws and marks it. ``pos`` is the fractional hour on the same 0..23 axis as ``prob_history`` indices; ``peak_prob`` is the peak probability (0..100 pp) — named distinctly from ``NewsEventOut.prob`` (the *current* probability) to avoid the "now vs peak" confusion.
            - `pos` number, required: When the swing peaked, as a fractional hour on the same 0-23 axis as `prob_history` (0 = 24h ago, 23 = now).
            - `peak_prob` number, required: Probability at that snapshot, 0-100 (percentage points, not [0, 1]).
          - `is_entertainment` boolean, required: Entertainment market; hidden by default (`?include_entertainment=true`).
          - `is_microprediction` boolean, required: Narrow behavioural bet (e.g. 'will X say Y', tweet-count ranges); hidden by default (`?include_microprediction=true`).
          - `is_crypto` boolean, required: Crypto market; hidden by default (`?include_crypto=true`).
          - `is_sports` boolean, required: Sports market; hidden by default (`?include_sports=true`).
          - `is_weather` boolean, required: Weather market; hidden by default (`?include_weather=true`).
          - `children` NewsEventOut[]: Other qualifying markets of the same event, by score, highest first.
        - `image` string, nullable
      - NewsEventOut: One news row, shaped to the wireframe's `NewsEvent` type. Probabilities in this model are on a 0-100 scale, unlike the [0, 1] used by /events and /markets (app/news/refresh.py converts at the refresh boundary so news_signals stores displayable values).
        - `kind` 'event': Row type: "event" (this shape) or "cluster" (a topic group of events).
        - `source` string, required: Venue: polymarket, kalshi, manifold, myriad, limitless, predict, opinion or gemini.
        - `market_id` string, required: The venue's market id (markets.id).
        - `src` 'pm' | 'ka' | 'ma' | 'li' | 'op' | 'pr' | 'my' | 'gm', required: Two-letter venue code used by the website.
        - `event_id` string, nullable: Parent event id; pdata's page is https://pdata.world/events/{source}/{event_id}. Null for orphan markets.
        - `question` string, nullable: The market's question as the venue titles it.
        - `group_item_title` string, nullable: Short outcome label within a multi-outcome event.
        - `event_title` string, nullable: Title of the parent event.
        - `cat` string, nullable: Primary pdata category of the row.
        - `categories` string[]: All pdata categories of the parent event.
        - `countries` string[]: Countries the market concerns, full English names, from pdata's AI tagging.
        - `prob` number, required: Current probability on a 0-100 scale (percentage points, e.g. 99.6) — news movers only; /events and /markets use [0, 1].
        - `d_prob` number, required: Signed change in percentage points: current `prob` minus the probability ~24h ago (the latest snapshot at or before then, else the oldest available). A row qualifies on any intra-day swing of 15+ points, so this can be small when the price went up and came back.
        - `vol_24hr` number, required: The market's venue-reported 24h volume, in the venue's own unit (shares for Polymarket, contracts for Kalshi, mana for Manifold).
        - `normalized_vol` number, required: `vol_24hr` on a 0-100 log scale within its venue (the market's `normalized_vol_24hr`); comparable across venues.
        - `end_date` string, date-time, nullable: Scheduled close, as the venue reports it (UTC).
        - `closed_time` string, date-time, nullable: When the venue closed the market (UTC).
        - `status` 'open' | 'closing-soon' | 'resolved', required: open, closing-soon (ends within 36 hours, or end date passed but not yet closed) or resolved (closed by the venue).
        - `is_resolved` boolean, required: True when `status` is resolved.
        - `url` string, nullable: The market's page on the venue's own website.
        - `event_url` string, nullable: The parent event's page on the venue's own website.
        - `image` string, nullable: Market image URL published by the venue.
        - `event_image` string, nullable: Parent event image URL published by the venue.
        - `spike_kind` 'prob': What moved. Always "prob" (probability).
        - `score` number, required: Ranking score: |d_prob| x log10(1 + 24h volume in USD terms), with Manifold mana counted at 0.01 USD. Higher ranks first.
        - `prob_history` number[]: 24 hourly probabilities on the 0-100 scale, oldest first (index 0 = 24h ago, 23 = now); null for hours with no snapshot. Empty when there is no history.
        - `spike` NewsSpike: The news-qualifying probability swing, pinned for the chart. The hourly ``prob_history`` can bucket a sub-hour spike away; this carries the actual peak snapshot so the carousel chart draws and marks it. ``pos`` is the fractional hour on the same 0..23 axis as ``prob_history`` indices; ``peak_prob`` is the peak probability (0..100 pp) — named distinctly from ``NewsEventOut.prob`` (the *current* probability) to avoid the "now vs peak" confusion.
          - `pos` number, required: When the swing peaked, as a fractional hour on the same 0-23 axis as `prob_history` (0 = 24h ago, 23 = now).
          - `peak_prob` number, required: Probability at that snapshot, 0-100 (percentage points, not [0, 1]).
        - `is_entertainment` boolean, required: Entertainment market; hidden by default (`?include_entertainment=true`).
        - `is_microprediction` boolean, required: Narrow behavioural bet (e.g. 'will X say Y', tweet-count ranges); hidden by default (`?include_microprediction=true`).
        - `is_crypto` boolean, required: Crypto market; hidden by default (`?include_crypto=true`).
        - `is_sports` boolean, required: Sports market; hidden by default (`?include_sports=true`).
        - `is_weather` boolean, required: Weather market; hidden by default (`?include_weather=true`).
        - `children` NewsEventOut[]: Other qualifying markets of the same event, by score, highest first.
  - `_meta` ResponseMetaList: 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)