Polymarket Scraper — Markets, Odds, Order Books & Price History

Structured Polymarket data for analysts, traders, researchers and AI agents: search markets or whole events by keyword, category or tag, filter by volume / liquidity / price / end date, and optionally attach the live CLOB order book and price history for each market. Clean JSON per market or per event, straight from Polymarket's public Gamma and CLOB APIs.

No API key, no proxy, no browser. Made by Yadroo.

Use cases

• Odds dashboard — pull the top events by 24h volume (mode=events) and show the leading outcome of each with one call.
• Movers alert — sortBy=change24h + minAbsChange24h on a schedule to catch markets that moved ≥ 5 points in a day.
• Watchlist monitoring — pass slugs / eventSlugs of the markets you care about; add includeOrderBook for depth and spread.
• Research datasets — status=closed with endDateFrom/endDateTo to collect resolved markets and their outcomes for calibration studies.
• Macro / event risk — category=economy or tag=fed-rates to feed rate-decision probabilities into a model or a report.
• New-market discovery — sortBy=newest with onlyNew=true to get only markets created since the previous run.

Input

Field	Type	Default	Notes
mode	markets | events	markets	One row per Yes/No market, or one row per event with nested markets.
query	string	—	Keywords (AND, case-insensitive) in question / event title. Active markets use Polymarket's own search; closed ones are scanned locally (≤ 5,000).
queries	string[]	—	Several keyword phrases, kept when any matches (words inside a phrase are AND-ed). Max 20.
category	enum	—	Curated tag shortcut, see Reference. Overrides tag/tagId.
categories	enum[]	—	Several curated categories in one run; results merged and deduped by id.
tag	string	—	Any tag slug (e.g. fed-rates, cpi-release, champions-league).
tagId	string	—	Numeric Gamma tag id.
tagIds	string[]	—	Several numeric Gamma tag ids, fanned out like categories. Max 20 tag scopes in total.
status	active | closed | all	active	Closed rows include resolvedOutcome when detectable.
includeClosed	boolean	false	Legacy alias for status=all.
slugs / ids / conditionIds / eventSlugs	string[]	—	Exact lookups; skip search entirely.
sortBy	enum	volume24hr	volume24hr, volume, volume7d, liquidity, endDate, startDate, newest, change24h, competitive.
maxItems (limit)	integer 1–1000	25	Rows to return.
minVolume24h, minLiquidity, minTotalVolume	integer USD	—	Threshold filters.
minAbsChange24h	string 0–1	—	Minimum absolute 24h Yes-price move, e.g. "0.05".
minAbsChange7d	string 0–1	—	Minimum absolute 7-day Yes-price move (markets mode).
minAbsChange30d	string 0–1	—	Minimum absolute 30-day Yes-price move (markets mode).
yesPriceMin, yesPriceMax	string 0–1	0 / 1	Price band filter (drop near-certain markets).
endDateFrom, endDateTo	date	—	End-date window (ISO).
endingWithinHours	integer	—	Shortcut: endDateTo = now + N h.
excludeEndingWithinMinutes	integer	—	Drop markets closing in the next N minutes (too late to trade).
excludeNegRisk	boolean	false	Skip multi-outcome (neg-risk) markets.
includeOrderBook / orderBookDepth	boolean / 1–50	false / 5	CLOB book for the Yes token: best bid/ask, mid, spread, depth in USD, top levels.
includePriceHistory / historyInterval / historyFidelityMinutes	boolean / enum / 1–1440	false / 1w / 60	Yes-price time series (1h, 6h, 1d, 1w, 1m, max) with first/last/min/max/change.
includeDescription	boolean	true	Set false to drop the resolution-rules text.
fields	string[]	—	Keep only these top-level fields (id, fetchedAt always kept).
onlyNew	boolean	false	Return only ids not pushed by previous runs (state in KV store yadroo-polymarket-seen).

Reference

category values (curated tag shortcuts)

category	tag id	category	tag id	category	tag id
politics	2	sports	1	crypto	21
finance	120	geopolitics	100265	economy	100328
elections	144	pop-culture	596	world	101970
tech	1401	science	74	business	107
ai	439	weather	84	earnings	1013
games	100639	esports	64	middle-east	154
trump	126	bitcoin	235	ethereum	39
nfl	450	nba	745	mlb	100381
soccer	100350	tennis	864	ufc	279

Polymarket has ~10,000 tags; any of them works via tag (slug) or tagId. Find slugs in polymarket.com URLs or via https://gamma-api.polymarket.com/tags?limit=100&offset=0 (paginate by 100) and /tags/slug/{slug}. Frequently useful: fed-rates, fomc, cpi-release, jobs-report, us-presidential-election, global-elections, crypto-prices, hit-price, champions-league, oil, israel, iran, russia, ukraine.

Sort keys

sortBy	Gamma order	Direction
volume24hr	volume24hr	desc
volume	volumeNum	desc
volume7d	volume1wk	desc
liquidity	liquidityNum	desc
endDate	endDate	asc (ending soonest)
startDate	startDate	desc
newest	createdAt	desc
change24h	oneDayPriceChange	desc
competitive	competitive	desc (closest to 50/50 first)

Examples

Top 25 markets right now (default)

{}

Odds table of the biggest economy events

{ "mode": "events", "category": "economy", "maxItems": 20, "minVolume24h": 10000 }

Daily movers alert (≥ 5 points, real volume, not already decided)

{ "sortBy": "change24h", "minAbsChange24h": "0.05", "minVolume24h": 5000, "yesPriceMin": "0.05", "yesPriceMax": "0.95", "maxItems": 50 }

Multi-topic news desk: macro + crypto keywords across two categories, weekly movers only

{ "categories": ["economy", "crypto"], "queries": ["Fed", "CPI", "Bitcoin"], "minAbsChange7d": "0.1", "minVolume24h": 1000, "excludeEndingWithinMinutes": 60, "maxItems": 50 }

Watchlist with depth and one-week history

{ "eventSlugs": ["fed-decision-in-september-762"], "includeOrderBook": true, "orderBookDepth": 10, "includePriceHistory": true, "historyInterval": "1w", "historyFidelityMinutes": 60 }

Resolved markets of Q3 2026 for a calibration study

{ "status": "closed", "endDateFrom": "2026-07-01", "endDateTo": "2026-09-30", "sortBy": "volume", "maxItems": 1000, "includeDescription": false, "fields": ["question", "yesPrice", "resolvedOutcome", "volumeTotal", "endDate", "url"] }

Everything ending in the next 48 hours with ≥ $50k liquidity

{ "endingWithinHours": 48, "minLiquidity": 50000, "sortBy": "endDate", "maxItems": 200 }

Output

One item per market (mode=markets), trimmed:

{
  "id": "2252244",
  "question": "Will there be no change in Fed interest rates after the September 2026 meeting?",
  "slug": "will-there-be-no-change-in-fed-interest-rates-after-the-september-2026-meeting-615",
  "url": "https://polymarket.com/market/will-there-be-no-change-in-fed-…",
  "groupItemTitle": "No change",
  "event": { "id": "481717", "title": "Fed Decision in September?", "slug": "fed-decision-in-september-762", "url": "https://polymarket.com/event/fed-decision-in-september-762" },
  "tags": ["fomc", "economic-policy", "fed-rates", "jerome-powell"],
  "category": "economy",
  "outcomes": [{ "name": "Yes", "price": 0.205, "tokenId": "5615…3721" }, { "name": "No", "price": 0.795, "tokenId": "9705…3724" }],
  "yesPrice": 0.205, "noPrice": 0.795, "impliedProbability": 20.5,
  "lastTradePrice": 0.2, "bestBid": 0.2, "bestAsk": 0.21, "spread": 0.01,
  "change1h": null, "change24h": 0.01, "change7d": -0.29, "change30d": -0.5,
  "volume24h": 2811872.76, "volume7d": 13555778.82, "volume30d": 29740350.19, "volumeTotal": 36597423.05,
  "liquidity": 1069021.85, "competitive": 0.92,
  "startDate": "2026-05-13T21:23:13Z", "endDate": "2026-09-16T00:00:00Z", "createdAt": "2026-05-13T17:23:05Z", "hoursToEnd": 72.4,
  "active": true, "closed": false, "archived": false, "acceptingOrders": true, "negRisk": true,
  "resolved": false, "resolvedOutcome": null,
  "conditionId": "0xa3b3…ec9a", "questionId": "0x128d…4c902", "clobTokenIds": ["5615…3721", "9705…3724"],
  "orderBook": { "bestBid": 0.2, "bestAsk": 0.21, "mid": 0.205, "spread": 0.01, "bidDepthUsd": 342747.01, "askDepthUsd": 512004.3, "bids": [{ "price": 0.2, "size": 120500 }], "asks": [{ "price": 0.21, "size": 98000 }], "tickSize": 0.01, "minOrderSize": 5, "timestamp": "2026-09-12T23:35:16.000Z" },
  "priceHistory": { "interval": "1w", "fidelityMinutes": 60, "first": 0.495, "last": 0.205, "min": 0.19, "max": 0.51, "change": -0.29, "points": [{ "t": "2026-09-05T23:20:24.000Z", "p": 0.495 }] },
  "description": "The FED interest rates are defined in this market by…",
  "sourceUrl": "https://gamma-api.polymarket.com/markets/2252244",
  "fetchedAt": "2026-09-12T23:35:14.991Z"
}

Field	Meaning
yesPrice / noPrice	Current outcome prices (0–1 = probability). impliedProbability = Yes in %.
bestBid / bestAsk / spread	Top of book as reported by Gamma; orderBook holds the live CLOB snapshot when requested.
change1h/24h/7d/30d	Yes-price change in probability points.
volume24h/7d/30d/Total, liquidity	USD.
competitive	0–1, higher = closer to a coin-flip with two-sided interest.
hoursToEnd	Hours until endDate at fetch time (negative once past).
negRisk	Market is part of a multi-outcome (neg-risk) event.
resolved / resolvedOutcome	For closed markets: winning outcome when one price is ≥ 0.99.
clobTokenIds / conditionId / questionId	Identifiers for the CLOB / on-chain layers.
priceHistory.points[]	{t: ISO time, p: price} for the Yes token.

mode=events rows: id, title, slug, url, ticker, tags, category, seriesSlug, startDate, endDate, hoursToEnd, volume24h, volume7d, volumeTotal, liquidity, openInterest, competitive, commentCount, active, closed, negRisk, marketCount, topOutcome {title, yesPrice}, markets[] {id, question, groupItemTitle, slug, yesPrice, noPrice, volume24h, liquidity, closed}, resolutionSource, image, description, sourceUrl, fetchedAt.

Use it from code / agents

Apify API (curl)

curl -X POST "https://api.apify.com/v2/acts/yadroo~polymarket-markets/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"events","category":"economy","maxItems":10}'

JavaScript (apify-client)

import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('yadroo/polymarket-markets').call({ query: 'Fed', includeOrderBook: true, maxItems: 5 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();

Python (apify-client)

from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("yadroo/polymarket-markets").call(run_input={"sortBy": "change24h", "minAbsChange24h": "0.05", "maxItems": 20})
items = client.dataset(run["defaultDatasetId"]).list_items().items

MCP — add https://mcp.apify.com to your agent (Claude, Cursor, etc.) and call the yadroo/polymarket-markets tool with the same JSON input; the input schema is self-describing for the model.

Pricing

Pay per event: $0.001 per run start + $0.002 per item (market or event row). Typical runs: default top-25 ≈ $0.051; a 200-market movers scan ≈ $0.401; a 1,000-row research pull ≈ $2.001. Enrichment (order book / history) adds no per-item charge but makes runs slower — keep maxItems modest when enabled.

Limits & FAQ

• Freshness — live at fetch time; Gamma's volume24hr/price-change fields refresh roughly every minute. fetchedAt is on every row.
• Rate limits — the actor paces itself (≤ 100 rows per request, ~8 req/s, exponential backoff on 429/5xx). Polymarket's public APIs are not aggressively limited, but 1,000-row runs with both enrichments take a few minutes.
• Keyword search on closed markets scans up to 5,000 sorted markets locally; add a tag/category or a date window to narrow it. Polymarket's search only indexes active events.
• Missing category — assigned only when one of the curated tags is attached to the event; tags always lists what Polymarket attached.
• Errors — invalid input (unknown category, sortBy, bad price band) fails immediately with an explicit message; unreachable API fails after 4 retries instead of looping. Missing slugs are logged as warnings, not errors.
• Roadmap — trades/holders per market, event-level price history, webhooks-ready diff output.

---

Made by Yadroo. Related actors: kalshi-markets (US-regulated prediction markets), crypto-sentiment, coingecko-markets, google-news-search.