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

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

Only markets belonging to a recurring series.

min_volumestr

Minimum lifetime volume in USD.

min_liquiditystr

Minimum current liquidity in USD.

sortstr= "-created_at"

Sort field. Prefix with - for descending.

limitint= 100

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="United States vs. Australia",
    sort="-volume", take=2,
)
for market in markets:
    print(market.question, market.volume)

jsonResponse

{
  "data": [
    {
      "id": "2535afbf-082c-5117-...",
      "question": "Will United States win on 2026-06-19?",
      "status": "resolved",
      "outcomes": [
        { "name": "Yes", "last_price": 0.5950 },
        { "name": "No", "last_price": 0.4050 }
      ],
      "volume": 5863189.6773,
      "series_id": "soccer-fifwc"
    },
    {
      "id": "dfc3baf2-36c9-5182-...",
      "question": "Will Australia win on 2026-06-19?",
      "status": "resolved",
      "outcomes": [
        { "name": "Yes", "last_price": 0.1750 },
        { "name": "No", "last_price": 0.8250 }
      ],
      "volume": 3130253.4401,
      "series_id": "soccer-fifwc"
    }
  ],
  "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.

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

jsonResponse

{
  "id": "5916b8f2-91d6-5438-...",
  "platform": "polymarket",
  "question": "Will Gold (GC) hit (HIGH) $5,500 by end of June?",
  "market_type": "binary",
  "status": "active",
  "outcomes": [
    { "name": "Yes", "index": 0, "last_price": 0.7200 },
    { "name": "No", "index": 1, "last_price": 0.2800 }
  ],
  "volume": 287063.4080,
  "liquidity": 24500.0000,
  "open_time": 1766791758794,
  "close_time": 1782840600000,
  "event_id": "125865",
  "series_id": "what-will-gold-gc-hit",
  "series_recurrence": "monthly",
  "subtype": "barrier",
  "underlying": "GC"
}