# Polymarket Scraper — Markets, Odds & Price History (`s-r/polymarket-scraper`) Actor

Collect Polymarket markets with outcome odds, traded volumes, liquidity, event metadata and optional historical prices. Search by topic or tag, fetch market and event slugs, and export one record per market.

- **URL**: https://apify.com/s-r/polymarket-scraper.md
- **Developed by:** [SR](https://apify.com/s-r) (community)
- **Categories:** Business, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 1,000 markets

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Polymarket Scraper

The Polymarket Scraper collects public prediction markets with questions, outcome
odds, traded volumes, liquidity, event metadata and optional historical prices.
Each dataset row represents one market, with its outcome prices and history kept
together. Use the records for research datasets, topic monitoring, reporting or
comparison with other prediction market sources.

### What the Polymarket Scraper collects

A market record includes its question, market slug, condition ID, outcome names,
numeric prices, token IDs, total traded volume and volume over the last day, week,
month and year. It also includes liquidity, available bid and ask prices, the last
trade price, price changes, dates and the associated event. Where the source does
not publish an order book value, that value is null. Missing volume windows are
reported as zero, following the source's omitted-zero representation.

Polymarket prices are numbers between zero and one. A value of 0.695 represents
a market price of 69.5 cents per share. These market prices reflect trading at the
source; collecting a record does not assess whether a particular outcome will occur.
All token identifiers are strings so they retain their full precision when exported
to JSON, spreadsheets or database tables.

### Input

Leave the input empty to collect up to 100 open markets ordered by descending
24-hour traded volume. Set `max_items` to choose a total limit between one and
10,000 markets. Larger collections are gathered across pages automatically during
the Actor run. The dataset contains unique markets identified by their condition ID.

Use `search` for a topic such as `bitcoin` and `tag` for a category or tag slug such
as `crypto`, `politics` or `sports`. Search and tag filters can be combined. Search
discovers matching events and then collects full metadata for their markets, so
the returned records include the same volume and liquidity fields as ordinary
market lists. An unknown tag is reported as invalid input.

For exact collections, supply `market_slugs`, `condition_ids` or `event_slugs`.
Event slugs may also be full HTTPS Polymarket event URLs. You can combine these
selector lists; duplicate markets are delivered once. Explicit selectors take
priority over search, tag and minimum-volume filters, while the selected status
continues to apply. If some selectors have no match, the matched markets are still
delivered and the missing selectors appear in the collection warnings.

The `status` choices are `active`, `closed` and `all`. Active means the market has
not closed. Closed includes resolved markets. An event that has reached its
scheduled end time can still contain open markets until the source closes them.
The output status distinguishes `open`, `closed` and `resolved`.

Choose `sort_by` from `volume_24h`, `volume_1wk`, `volume_1mo`, `volume`, `liquidity`,
`end_date` and `start_date`. `ascending` changes the direction. Volume and liquidity
sorts are numeric. Search and explicit-selector results are sorted within each
collected page; search ranks events before their individual markets are collected.
Use `min_volume` and `min_liquidity` for USD thresholds in list and search mode.

```json
{"search":"bitcoin","tag":"crypto","status":"active","max_items":100,"include_price_history":true,"history_interval":"1w","history_fidelity":60}
```

### Price history

Set `include_price_history` to include a `price_history` object inside each market.
Its `outcomes` list contains an outcome name, token ID and `points` array. Each
point contains `t`, a Unix timestamp in seconds, and `p`, a numeric price between
zero and one. History does not create extra dataset rows.

The supported `history_interval` values are `1h`, `6h`, `1d`, `1w`, `1m` and `max`.
`history_fidelity` is the resolution in minutes, with a default of 60. Week history
requires at least five minutes; month history requires at least ten. Other intervals
accept one minute or more. Invalid settings are rejected before collection starts.
Long histories and finer resolutions are collected in smaller pages.

`history_outcomes` defaults to `all`. Select `first` to request only the first
outcome in source order. That outcome is not necessarily named Yes. Newly created,
inactive or unavailable tokens may have no history points. Such cases produce a
warning and retain the market row. If a requested history collection fails, the
output records the missing history and marks the collection as partial.

### Output and exports

Market rows are available in the default dataset for export as JSON, CSV or Excel.
Nested outcome and history structures are most directly represented in JSON.
`source`, `fetched_at`, `market_id` and `question` provide stable core fields.
`market_id` and `condition_id` contain the same condition ID; `gamma_id` is the
separate metadata identifier. Event fields include `event_id`, `event_title`,
`event_slug` and a public `url` when the source publishes the event association.

Volume and liquidity fields use USD. `fetched_at` records when data was collected;
the source may cache metadata for up to five minutes, so a snapshot is not a
stream of individual trades. Scheduled start and end dates describe the source's
market schedule, not the time of the last price update. The Actor's OUTPUT record
contains delivered counts and collection warnings for reviewing an incomplete run.

### Example output

This is an excerpt of one real market row, collected with `{"max_items": 1}`. The full row
also holds the description, token IDs per outcome, price changes and status fields.

```json
{
  "source": "polymarket-scraper",
  "fetched_at": "2026-10-12T01:32:00Z",
  "question": "49ers vs. Seahawks",
  "condition_id": "0xb8f8ac0fbc08449be5f6d4eff0bfe05d68d4feacce05b94f0318799f5a24186d",
  "slug": "nfl-sf-sea-2026-10-11",
  "outcomes": [
    {
      "name": "49ers",
      "price": 0.605,
      "token_id": "42158923980605321293165440276929675077899618107237728886385329948641645877896"
    },
    {
      "name": "Seahawks",
      "price": 0.395,
      "token_id": "98905985735656534874399889933780300059476082879846776272208832784485523440286"
    }
  ],
  "status": "open",
  "event_title": "49ers vs. Seahawks",
  "url": "https://polymarket.com/event/nfl-sf-sea-2026-10-11",
  "volume": 3709409.229131,
  "liquidity": 512467.8813,
  "volume_24h": 3721187.8384300005,
  "volume_1wk": 3754430.437635001,
  "volume_1mo": 3757153.940591001,
  "best_bid": 0.6,
  "best_ask": 0.61,
  "last_trade_price": 0.61,
  "start_date": "2026-08-31T12:00:52Z",
  "end_date": "2026-10-11T20:25:00Z"
}
```

### Use cases

- **Trading research:** compare implied probabilities across markets, rank them by 24-hour volume and keep
  a dated history of how the odds moved.
- **Journalism and media:** pull the current odds on an election, a court case or a sports final with
  volume and liquidity attached, so you can tell a thin market from a deep one.
- **Data science:** build a dataset of resolved markets with their price history for calibration studies
  and forecasting models.
- **Monitoring:** schedule a run on a topic or tag and track which markets gain volume this week.
- **Comparison with other prediction markets:** every row has the same market, outcome and price fields,
  so it can be joined with data from other sources on topic or date.

### Polymarket Scraper compared with the alternatives

| | Polymarket Scraper | Calling the Polymarket API yourself | Ad hoc scripts from GitHub |
|---|---|---|---|
| Setup | Fill in a form or send JSON | Read the API docs, handle paging and rate limits | Install, configure, maintain |
| Output | One flat row per market, nested price history | Several endpoints with different shapes | Varies per script |
| Large collections | Paging handled in the run, up to 10,000 markets | Offset limits require a different paging method | Often stops at the first page |
| Exports | JSON, CSV, Excel, API | Your own code | Your own code |
| Scheduling | Apify schedules and webhooks | Your own infrastructure | Your own infrastructure |

If you only need a handful of markets once, the Polymarket API is free to call directly. The Polymarket
Scraper is for the Polymarket API data you want repeatedly, cleaned and in one table, for example
Polymarket odds on a weekly schedule or Polymarket historical data for hundreds of markets.

### Pricing

Billing uses one `market` event for each market actually delivered to the dataset.
Outcome lists and requested price history are included in that market row and do
not add separately billed rows. The current event price is displayed in the Apify
pricing panel. A collection with no matching markets has no market event charges.
Non-paying users can receive at most ten markets per run, including requested
history. This delivery cap does not change the meaning of the market pricing event.

### FAQ

#### Can I collect already resolved markets?

Yes. Set `status` to `closed` or `all`, including when you provide exact market
slugs or condition IDs. Resolved markets carry output status `resolved` when the
source reports that resolution explicitly.

#### Does one event produce one dataset row?

An event can contain several markets, so one event slug can produce several
dataset rows. Each row has its own question, condition ID and outcome list. The
total `max_items` limit and the non-paying delivery cap apply to market rows.

#### Why is an outcome's price history empty?

The source may not have published historical points for that token or period.
Check the warnings to distinguish an empty historical series from a failed history
request. In both cases the market snapshot remains available in the dataset.

#### How do I get more than 100 markets?

Increase `max_items`. The Actor follows continuation pages automatically within
its run budget. If the source fails during a collection, earlier delivered markets
are preserved and the run output explains the incomplete portion.

# Actor input Schema

## `search` (type: `string`):

Search public Polymarket events; matching markets are fetched with full metadata.

## `tag` (type: `string`):

Category or tag slug, such as crypto, politics or sports.

## `event_slugs` (type: `array`):

Event slugs or full https://polymarket.com/event/<slug> URLs. Explicit selectors take priority over search and tag filters.

## `market_slugs` (type: `array`):

Market slugs to fetch. Explicit selectors take priority over list filters.

## `condition_ids` (type: `array`):

Market condition IDs, each 0x followed by 64 hexadecimal characters.

## `status` (type: `string`):

active selects markets with closed=false; closed includes resolved markets; all includes both.

## `sort_by` (type: `string`):

Sort delivered markets numerically by volume or liquidity, or by date. Search and explicit selectors sort each delivered page.

## `ascending` (type: `boolean`):

Sort in ascending order.

## `min_volume` (type: `number`):

Minimum total traded volume in USD for list and search modes.

## `min_liquidity` (type: `number`):

Minimum liquidity in USD for list and search modes.

## `max_items` (type: `integer`):

Maximum total markets to deliver. A request returns up to 100; continue with cursor for larger collections. Apify follows cursors automatically.

## `include_price_history` (type: `boolean`):

Include price history for selected outcomes within each market row.

## `history_interval` (type: `string`):

Price history interval. max uses a smaller request page to limit memory.

## `history_fidelity` (type: `integer`):

History resolution in minutes. Minimum 5 for 1w, 10 for 1m, otherwise 1. Values below 60 use a smaller page.

## `history_outcomes` (type: `string`):

Fetch all outcomes or only the first outcome in source order.

## `cursor` (type: `string`):

Opaque next_cursor from the previous response. Repeat the same filters; the original total limit is preserved.

## Actor input object example

```json
{
  "status": "active",
  "sort_by": "volume_24h",
  "ascending": false,
  "max_items": 100,
  "include_price_history": false,
  "history_interval": "1w",
  "history_fidelity": 60,
  "history_outcomes": "all"
}
```

# Actor output Schema

## `results` (type: `string`):

Delivered markets in the default dataset.

## `output` (type: `string`):

Delivered counts and collection warnings.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("s-r/polymarket-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("s-r/polymarket-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call s-r/polymarket-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,s-r/polymarket-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Iecza7M9ENMF5Semc/builds/Ubh8bzWwHTFPRgnWE/openapi.json