MTG Metagame Scraper

Apify Actor that scrapes Magic: The Gathering competitive metagame data: archetype meta shares, recent tournaments with an importance rating, standings with player names, and full decklists of the top finishes.

Supported formats: standard, modern, legacy, vintage, pioneer, commander, pauper.

Data sources

	MTGTop8 (default)	MTGGoldfish
Archetype meta shares	✅	✅
Archetype key cards	❌	✅
Real tournaments with standings	✅	❌
Tournament importance (1–5 stars)	✅	❌
Full decklists (main + sideboard)	✅	❌

Pick the source with the source input option (mtgtop8, mtggoldfish, or both).

Input

{
    "formats": ["modern", "standard"],
    "source": "mtgtop8",
    "maxEvents": 8,
    "minPlayers": 100,
    "decklistsPerEvent": 2,
    "includeDecklists": true,
    "requestDelaySecs": "1.0",
    "incremental": false,
    "stateRetentionDays": 30
}

• formats — which formats to scrape.
• source — data source: mtgtop8 (tournaments + decklists), mtggoldfish (meta shares + key cards), or both.
• maxEvents (MTGTop8 only) — tournaments per format, picked by importance (star rating) then recency.
• minPlayers (MTGTop8 only) — skip tournaments below this size. Player counts are only visible on event pages, so up to 3× maxEvents events are probed. Tip: use 50 for smaller formats like Vintage or Legacy.
• decklistsPerEvent (MTGTop8 only) — full decklists (top finishes) downloaded per tournament.
• requestDelaySecs — polite delay between requests (keep ≥ 1.0).
• incremental (MTGTop8 only) — remember tournament ids across runs (in the named key-value store mtg-metagame-seen-events) and only emit NEW events. MTGTop8's format page only shows the last few days, so a scheduled incremental run accumulates tournament history over time with no duplicates — and already-seen tournaments cost no extra requests (fewer paid results, faster runs). The metagame item (meta shares) is always emitted: it is a point-in-time snapshot, not an accumulating stream.
• stateRetentionDays — days before a seen tournament id is forgotten (keeps the incremental state from growing forever). Default 30.

Output

Dataset items come in two shapes, discriminated by type.

metagame — one per format+source:

{
    "type": "metagame",
    "format": "modern",
    "source": "mtgtop8",
    "fetched_at": "2026-07-15T10:00:00+00:00",
    "total_archetypes": 49,
    "archetypes": [
        {"name": "Boros Aggro", "meta_share": 0.11, "category": "Aggro"}
    ]
}

MTGGoldfish archetypes have key_cards instead of category.

event — one per qualifying tournament (MTGTop8 only):

{
    "type": "event",
    "format": "modern",
    "source": "mtgtop8",
    "id": "88185",
    "name": "MTGO Showcase Challenge",
    "stars": 3,
    "importance": "major",
    "date": "12/07/26",
    "online": true,
    "players": 448,
    "decks": [
        {
            "deck_id": "869090",
            "rank": "1",
            "archetype": "Ruby Storm",
            "player": "Fatone",
            "decklist": {
                "mainboard": [{"qty": 4, "card_name": "Ruby Medallion"}],
                "sideboard": [{"qty": 4, "card_name": "Orim's Chant"}]
            }
        }
    ]
}

Only the first decklistsPerEvent decks carry a decklist.

rank is a string, possibly composite ("1", "3-4", "5-8"): shared placements are how MTGTop8 reports brackets below the finals. Don't parse it as an integer — sort by its first number if you need an ordering.

Note: no source exposes reliable per-archetype win rates for free; that is why the output deliberately has no win-rate field.

Notes on importance (stars)

MTGTop8 rates events 1–5 stars. The scraper prioritizes tournaments by stars, then recency, and maps them to labels: minor (≤1★), competitive (2★), major (3★), premier (4–5★). Use this to weight results: a Top 8 at a premier event says more about the metagame than a win at a small local.

Use as a library

The parsers live in the installable mtg_metagame package — this repo is the single source of truth for them (the DeckAssistant backend consumes it as a pip dependency):

$pip install "mtg-metagame @ git+ssh://git@github.com/MartoEporedia/mtg-metagame-actor.git"

from mtg_metagame import MTGTop8Client

client = MTGTop8Client()
data = await client.fetch_metagame_full("modern", max_events=8, min_players=100)

Override PoliteClient.fetch to plug in your own caching or transport.

Running locally

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
apify run   # or: python -m src (reads storage/key_value_stores/default/INPUT.json)

Fair use

The scraper enforces a ≥1s delay between requests and fetches a bounded number of pages per run (roughly formats × (1 + 3×maxEvents + maxEvents×decklistsPerEvent) worst case). Please keep the delay at 1 second or higher. MTGGoldfish sits behind Cloudflare: if requests get blocked on the platform, enable Apify Proxy.