How do I search Polymarket markets programmatically?

GET /v1/markets?q=... returns markets matching a text query. You can also filter by tag, status (open/resolved), and resolution date range.

What metadata does a Polymarket market include?

Market ID, slug, question, outcomes, resolution date, tags, status, creator, and last price. Full schema is documented at marketlens.trade/docs/markets.

Data

Markets

Discover, filter, and retrieve prediction market metadata.

GET/markets

sdkclient.markets.list(**params)

Returns a paginated list of markets matching the given filters.

Parameters

platformstr

Filter by source platform, e.g. "polymarket".

statusstr

Filter by market status: "active", "closed", "resolved", or "pending".

qstr

Full-text search on market question.

event_qstr

Full-text search on parent event title.

event_idstr

Filter by parent event UUID.

series_idstr

Filter by parent series slug or UUID.

subtypestr

Filter to one bet type within a series (e.g. "moneyline", "total", "spread").

categorystr

Filter by event category.

condition_idstr | list

Filter by Polymarket condition ID(s). Up to 50.

recurringbool

True = only recurring-series markets, false = only standalone markets.

min_volumefloat

Minimum cumulative volume in USD.

min_liquidityfloat

Minimum current liquidity in USD.

open_afterint | str

Markets that opened at or after this time (ms epoch or ISO 8601).

open_beforeint | str

Markets that opened at or before this time (ms epoch or ISO 8601).

close_afterint | str

Markets closing at or after this time (ms epoch or ISO 8601).

close_beforeint | str

Markets closing at or before this time (ms epoch or ISO 8601).

resolved_afterint | str

Markets resolved at or after this time (ms epoch or ISO 8601).

resolved_beforeint | str

Markets resolved at or before this time (ms epoch or ISO 8601).

sortstr= "-created_at"

Sort field. Prefix with - for descending.

limitint= 500

Results per page.

cursorstr

Pagination cursor from previous response.

takeint

SDK only. Caps total items returned across pages.

Info

The SDK iterator auto-paginates. Use .to_list() to collect all results or .to_dataframe() for a pandas DataFrame.

markets = client.markets.list(
    event_q="Presidential Election Winner 2028",
    sort="-volume", take=2,
)
for market in markets:
    print(market.question, market.volume)

jsonResponse

{
  "data": [
    {
      "id": "66352f1f-b765-5262-...",
      "question": "Will LeBron James win the 2028 US Presidential Election?",
      "status": "active",
      "outcomes": [
        { "name": "Yes", "last_price": 0.0005 },
        { "name": "No", "last_price": 0.9995 }
      ],
      "volume": 54783195.7641,
      "series_id": null
    },
    {
      "id": "8a1a2b4e-bc72-5838-...",
      "question": "Will Tim Walz win the 2028 US Presidential Election?",
      "status": "active",
      "outcomes": [
        { "name": "Yes", "last_price": 0.0005 },
        { "name": "No", "last_price": 0.9995 }
      ],
      "volume": 44726788.1251,
      "series_id": null
    }
  ],
  "meta": { "cursor": "...", "has_more": true }
}

GET/markets/{market_id}

sdkclient.markets.get(market_id)

Retrieve a single market by UUID, or by its Polymarket condition id (0x followed by 64 hex characters). UUIDs are Marketlens identifiers; Polymarket's own identifiers are condition ids and series slugs.

Response fields

idstr

Marketlens market UUID.

platformstr

Source platform, currently always "polymarket".

platform_market_idstr

Polymarket condition ID (0x followed by 64 hex characters).

event_idstr

UUID of the parent event.

event_titlestr | None

Title of the parent event.

categorystr | None

Topic category, e.g. "Crypto", "Sports".

series_idstr | None

UUID of the parent series, null for standalone markets.

series_titlestr | None

Title of the parent series.

series_recurrencestr | None

Recurrence interval: "5m", "15m", "hourly", "daily", "weekly", or "monthly".

questionstr

The market question.

market_typestr

"binary" (two outcomes) or "scalar".

statusstr

"active", "closed", "resolved", or "pending".

outcomeslist

Outcome objects with name, index, platform_token_id, and last_price.

winning_outcomestr | None

Name of the winning outcome after resolution.

winning_outcome_indexint | None

Index of the winning outcome after resolution.

tick_sizefloat

Minimum price increment.

volumefloat | None

Cumulative traded volume in USD.

liquidityfloat | None

Current resting liquidity in USD.

open_timeint | None

When trading opened (ms epoch).

close_timeint | None

When trading closes (ms epoch).

resolved_atint | None

When the market resolved (ms epoch).

platform_resolved_atint | None

When the platform recorded resolution (ms epoch).

created_atint

Record creation time (ms epoch).

updated_atint

Last metadata update (ms epoch).

strikefloat | None

Strike price for structured products.

strike_upperfloat | None

Upper strike for range markets.

strike_directionstr | None

Strike direction: "above", "below", "between", "reach", or "dip".

subtypestr | None

Backtest cohort key, e.g. "up_or_down", "barrier", "moneyline", "total", or "rest" if unclassified.

underlyingstr | None

Underlying asset symbol derived from the question, e.g. "BTC", "GC".

collection_tierstr | None

"streamed" = full snapshot and delta chain, "polled" = periodic snapshots without deltas, null = collected before tiers existed (streamed).

game_start_timeint | None

When the real-world game starts (ms epoch), null outside sports and esports.

sports_market_typestr | None

Platform bet-type slug, e.g. "moneyline", "spreads", "totals" (70+ values), null outside sports and esports.

linefloat | None

Spread or total line for sports bets (e.g. -6.5), null otherwise.

neg_riskbool | None

True when the market is one leg of a negative-risk group (mutually exclusive outcomes of one event).

data_startint | None

First order book recorded for the market, after open_time (ms epoch).

data_endint | None

Last order book recorded for the market, at resolution (ms epoch). Null while the market is open.

market = client.markets.get(
    "4ee145e2-3fee-5b15-bb95-56a33a292945"
)
print(market.question, market.status, market.underlying)

jsonResponse

{
  "id": "eca78376-8d28-5bca-963c-b8f10c13b2b8",
  "platform": "polymarket",
  "platform_market_id": "0x04a4099fc3b9bc4c6617381d4237f28953ce24f0eaecbc4e36db09baec2906ec",
  "event_id": "e3322caa-9000-5340-ba79-5e6dc5fe8d2f",
  "event_title": "What price will Bitcoin hit August 24-30?",
  "category": "Crypto",
  "series_id": "28e445ae-5528-5309-a633-11e3141e546d",
  "series_title": "Bitcoin Hit Price Weekly",
  "series_recurrence": "weekly",
  "question": "Will Bitcoin reach $90,000 August 24-30?",
  "market_type": "binary",
  "status": "resolved",
  "outcomes": [
    {
      "name": "Yes",
      "index": 0,
      "platform_token_id": "53453370243063477080422334278533913021612067816754192932224759490923681193118",
      "last_price": 0.0305
    },
    {
      "name": "No",
      "index": 1,
      "platform_token_id": "56567584604265326602898105196455943598304967161931700674740159564630048598423",
      "last_price": 0.9695
    }
  ],
  "winning_outcome": "No",
  "winning_outcome_index": 1,
  "tick_size": 0.01,
  "volume": 188.679244,
  "liquidity": 12776.93891,
  "open_time": 1787544019000,
  "close_time": 1788148800000,
  "resolved_at": 1788149689628,
  "platform_resolved_at": 1788149689603,
  "created_at": 1787561340247,
  "updated_at": 1787562166144,
  "strike": 90000.0,
  "strike_upper": null,
  "strike_direction": "reach",
  "subtype": "barrier",
  "underlying": "BTC",
  "collection_tier": "streamed",
  "game_start_time": null,
  "sports_market_type": null,
  "line": null,
  "neg_risk": false,
  "group_item_title": "↑ 90,000",
  "data_start": 1787561410759,
  "data_end": 1788149689603
}