Polymarket Scraper — Markets, Odds & Prices API

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 — an independent tool, not affiliated with or endorsed by Polymarket.

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. Values off the list are refused by Apify before the run.
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). The run looks it up and filters by its tag id; a slug Polymarket does not have fails the run with a message (it never falls back to unfiltered markets). Case and surrounding spaces do not matter (reported in the status).
tagId	string	—	Numeric Gamma tag id. Unknown ids fail the run; with tag, both must name the same tag.
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 and tags (status and the min*/price/date filters still apply). slugs/ids/conditionIds are market lookups (markets mode only).
sortBy	enum	volume24hr	volume24hr, volume, volume7d, liquidity, endDate, startDate, newest, change24h, competitive.
maxItems (limit)	integer 1–1000	25	Rows to return. The run also stops at your maximum cost per run.
minVolume24h, minLiquidity, minTotalVolume	integer USD	—	Threshold filters.
minAbsChange24h	string 0–1	—	Minimum absolute 24h Yes-price move, e.g. "0.05" (markets mode).
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; markets mode).
endDateFrom, endDateTo	date	—	End-date window: YYYY-MM-DD (UTC; endDateTo counts through the end of that day) or an ISO date-time.
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, in your order; id and fetchedAt are always kept (first, unless you list them elsewhere). Case and _/- are forgiven; names the mode does not have are skipped with a note and a suggestion; the run fails if none exists.
onlyNew	boolean	false	Return only markets/events not delivered by previous runs (memory in the named KV store yadroo-polymarket-seen, one record per mode, deliveries forgotten after 90 days). Only rows really saved are remembered.

The 0–1 fields and the dates are checked by Apify before the run starts: a value such as "abc", "5%" or "tomorrow" is refused with a message, so a typo never turns into "no filter".

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

Off-list values of the enum fields (mode, category, categories, status, sortBy, historyInterval) are refused by Apify before the run (HTTP 400, nothing is charged); use the values exactly as listed.

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 (with fields, id and fetchedAt come first, then your fields in your order):

{
  "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; 0 when the price did not move, null while the market is younger than that window.
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.

Store discounts: Bronze −10 %, Silver −20 %, Gold and above −30 % on the row price; the start event is the same on every plan. Platform usage is included.

Maximum cost per run is respected: the run saves only the rows your limit pays for, then ends with the status "Stopped at your spending limit: N rows delivered". With onlyNew, the rows it did not save are not remembered and come in the next run.

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.
• Empty price changes — Gamma sends no value when a change is zero, so the actor reports 0 for an open market that already traded through the whole window. A market listed inside the window keeps null (there is no earlier price to compare with): Polymarket lists whole batches of daily/monthly strike markets at once, so a fresh batch can fill much of a sortBy=volume24hr top list with change24h: null rows. sortBy=newest plus includePriceHistory shows what those markets did since they opened.
• Errors — enum values off the list are refused by Apify before the run starts (no charge). Inputs the actor checks itself (an unknown tag/tagId, a price band with min > max, unknown fields) fail the run at once with a message that names the field. An unreachable API fails after a few retries instead of looping. Missing slugs are logged as warnings, not errors.
• Timeouts — a run near its timeout stops starting new requests, saves the rows it has, and ends SUCCEEDED with "Stopped before the run timeout: N rows saved". A 1,000-row run with both enrichments takes several minutes; the default timeout (15 min) covers it.
• Summary — every run writes a SUMMARY record (rows saved, rows skipped by onlyNew, tags used with their ids, input notes, enrichment failures).
• Roadmap — trades/holders per market, event-level price history, webhooks-ready diff output.

---

Made by Yadroo. Not affiliated with, endorsed by or sponsored by Polymarket; "Polymarket" is used only to name the public data source. Related actors: kalshi-markets (US-regulated prediction markets), crypto-sentiment, coingecko-markets, google-news-search.