> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Polymarket Markets API

> Polymarket prediction markets: each market is a yes/no or multi-outcome question people bet on, with live odds, trading volume and end date. Browse a category such as Politics or Crypto, search by keyword (e.g. bitcoin, election), or paste polymarket.com event links.

`POST /v1/data/polymarket/markets/run`

**Pricing:** $0.0005 per market ($0.5 per 1,000).

## Ways to call it

* **Browse**: set `category` (optional: `status`, `sortBy`, `maxResults`)
* **Keyword search**: set `query` (optional: `status`, `sortBy`, `maxResults`)
* **By URL or slug**: set `urls` (optional: `sortBy`, `maxResults`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**category** `string`

Browse: one of Polymarket's categories (e.g. Politics, Crypto, Sports). Returns the markets in it, biggest first. No search term needed.

Allowed values: `politics` (Politics), `sports` (Sports), `crypto` (Crypto), `finance` (Finance), `economy` (Economy), `geopolitics` (Geopolitics), `tech` (Tech), `ai` (AI), `pop-culture` (Culture), `world` (World), `elections` (Elections), `business` (Business), `science` (Science), `weather` (Weather), `earnings` (Earnings), `esports` (Esports).

**query** `string`

Keyword search: a topic, person, asset or event to find markets about (e.g. bitcoin, election, Fed rates).

**urls** `string[]`

By URL: polymarket.com/event/... links (or just the event slug, e.g. what-price-will-bitcoin-hit-before-2027). Returns every market in each event; a link that ends in a market slug returns just that market.

**status** `string` (default: active)

Open markets you can still trade (active, the default) or finished ones with a known outcome (resolved).

Allowed values: `active` (Active | currently open), `resolved` (Resolved | completed markets).

**sortBy** `string` (default: volume)

How markets are ordered. Defaults to total volume (most-traded first).

Allowed values: `volume` (Total volume (all-time activity)), `volume_24hr` (24h volume (recent activity)), `liquidity` (Liquidity (deepest markets)), `start_date` (Start date (newest markets)), `ending_soon` (Ending soon (closes soonest)), `competitive` (Competitive (balanced odds)).

**maxResults** `integer` (default: 100)

How many markets to return in total. Defaults to 100; use 0 for all.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/polymarket/markets/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "category": "politics",
    "sortBy": "volume",
    "maxResults": 10
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/polymarket/markets/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "category": "politics",
    "sortBy": "volume",
    "maxResults": 10
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/polymarket/markets/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "category": "politics",
  "sortBy": "volume",
  "maxResults": 10
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one market, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `marketId` | Market ID | text |
| `question` | Question | text |
| `url` | URL | url |
| `groupLabel` | Group Label | text |
| `eventId` | Event ID | text |
| `eventTitle` | Event Title | text |
| `status` | Status | text |
| `outcomes` | Outcomes | object\_array |
| `pricing` | Pricing | object |
| `volume` | Volume | currency |
| `volume24h` | Volume 24h | currency |
| `volume1w` | Volume 1w | currency |
| `liquidity` | Liquidity | currency |
| `eventVolume` | Event Volume | currency |
| `priceChange24h` | Price Change 24h | number |
| `priceChanges` | Price Changes | object |
| `startDate` | Start Date | datetime |
| `endDate` | End Date | datetime |
| `tags` | Tags | array |
| `rules` | Rules | text |
| `resolutionSource` | Resolution Source | url |
| `conditionId` | Condition ID | text |
| `image` | Image | image |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "polymarket/markets",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "groupLabel": null,
      "rules": "This market will resolve to \"Yes\" if the United States commences a military offensive intended to establish control over any portion of Iran by December 31, ...",
      "liquidity": 412271.2181,
      "priceChanges": {
        "one_week": -0.07,
        "one_month": -0.06
      },
      "eventId": "73130",
      "startDate": "2025-11-05T17:52:17.414Z",
      "pricing": {
        "last_trade_price": 0.11,
        "best_ask": 0.11,
        "best_bid": 0.1,
        "spread": 0.01,
        "favorite_outcome": "No",
        "favorite_price": 0.895
      },
      "volume1w": 2262382.912896,
      "endDate": "2027-01-01T04:59:00Z",
      "resolutionSource": null,
      "marketId": "665374",
      "question": "Will the U.S. invade Iran before 2027?",
      "volume24h": 144812.808169,
      "outcomes": [
        {
          "name": "Yes",
          "price": 0.105
        },
        {
          "name": "No",
          "price": 0.895
        }
      ],
      "url": "https://polymarket.com/event/will-the-us-invade-iran-before-2027",
      "eventVolume": 78341405.79391801,
      "eventTitle": "Will the U.S. invade Iran before 2027?",
      "status": "active",
      "tags": [
        "U.S. x Iran",
        "Macro Geopolitics"
      ],
      "volume": 78342023.24846402,
      "conditionId": "0x5db999fad322cea2914535aae5517060c3f80ad6d8c0231cde2124a434d16846",
      "image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/will-the-us-invade-iran-in-2025-0Eh3J0ku_Fbj.jpg",
      "priceChange24h": -0.01
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.