MTGGoldfish API & Scraper: parameters and responses
This is the reference for the 16 MTGGoldfish endpoints under /mtggoldfish/v1 (search, autocomplete, card, price_history, sets, set, set_history, movers, staples, metagame and 6 more) and their 33 parameters. Each endpoint lists its parameters, required or optional, with allowed values and defaults, and comes with a cURL, Python and JavaScript call; every response uses the same { ok, data, meta, error } envelope.
The MTGGoldfish API returns Magic: The Gathering market and tournament data as clean JSON, with tabletop prices in USD and Magic Online prices in tix kept apart in named fields.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
search finds cards by name, 20 a page, with both prices, rarity and set. card returns one printing in full: its tabletop and MTGO price, daily and weekly change, all-time high and low, spread, highest buylist and foil multiplier, the sell and buylist quotes shown from Card Kingdom, TCGplayer Mid and Cardhoarder, every other printing with its prices, oracle text, legalities in every format and images. price_history gives every daily price since the card was released (Sheoldred, the Apocalypse: 1,533 daily points from 2022-08-18), as two series, tabletop USD and MTGO tix. set lists a whole set with both prices and each card's daily and weekly change, and set_history charts the total value of the set. movers returns the day's and week's biggest risers and fallers for a format or set. metagame returns each archetype's share of the field, deck count, tabletop and MTGO deck price and key cards over 7, 14, 30, 90 or 365 days, for tabletop or MTGO results. staples ranks the most played cards in a format. archetype, deck, deck_search, tournaments and tournament cover decklists, with event, place and record, and every card's price in both currencies. No account, no browser - one ReefAPI key and the standard { ok, data, meta, error } envelope.
Tabletop dollars and MTGO tix are two different markets
MTGGoldfish tracks each printing twice: the tabletop price in USD and the Magic Online price in tix, and they move independently. The API never merges them or converts one into the other: every field names its currency. These are the numbers we read live on 2026-11-08.
| Printing | paper_price_usd | online_price_tix | Note |
|---|---|---|---|
| Black Lotus (Limited Edition Alpha) | 74,981.00 | 491.06 | All-time tabletop high 81,421.00; highest buylist 68,000.00 |
| Ragavan, Nimble Pilferer (Modern Horizons 2) | 43.49 | 7.75 | Tabletop spread 24%; Card Kingdom buylist 33.00 |
| Ragavan, Nimble Pilferer (Modern Horizons 2) Foil | 71.36 | 6.80 | On MTGO the foil was worth less than the non-foil that day |
| Sol Ring (Masters Edition IV) | null | 4.42 | An MTGO-only printing has no tabletop price: null, never 0 |
These are the site's listing-based prices, not completed sales: the tabletop figure matched the page's TCGplayer Mid row on 5 of 5 cards we audited and the MTGO figure matched its Cardhoarder row on 6 of 6. A null means the site shows no price in that market. Card pages show listing-based prices and vendor quotes rather than completed sales, and the API does not use an account.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/mtggoldfish/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "dragon"
}
}{
"ok": true,
"meta": {
"api": "mtggoldfish",
"endpoint": "search",
"mode": "live",
"latency_ms": 1112.8,
"record_count": 20,
"bytes": 75821,
"cache_hit": false,
"total": 374,
"page": 1,
"per_page": 20,
"last_page": 19,
"has_more": true,
"upstream_requests": 1,
"sort": "relevance",
"sort_direction": "asc",
"charged_credits": 1,
"version": "1.0.0",
"request_id": "7faa7833f43d409e",
"queue_ms": 2.2,
"fetched_at": "2026-11-08T13:04:29.112Z"
},
"data": {
"rows": [
{
"name": "Dragon Appeasement",
"card_id": "Dragon Appeasement [ARB]",
"set_code": "ARB",
"set": "Alara Reborn",
"collector_number": "115",
"finish": "regular",
"foil": false,
"variant": null,
"rarity": "Uncommon",
"paper_price_usd": 0.25,
"online_price_tix": 0.03,
"image": "https://cards.mtggoldfish.com/images/019ce2ef-2caf-765a-9e55-f3ab54e5b0ab/variants/265/370/card_image.webp",
"url": "https://www.mtggoldfish.com/price/alara-reborn/115/dragon-appeasement"
},
{
"name": "Dragon Arch",
"card_id": "Dragon Arch [AP]",
"set_code": "AP",
"set": "Apocalypse",
"collector_number": "135",
"finish": "regular",
"foil": false,
"variant": null,
"rarity": "Uncommon",
"paper_price_usd": 2.16,
"online_price_tix": 0.04,
"image": "https://cards.mtggoldfish.com/images/019ce2ef-3078-7b4b-b1b2-5bfb07972426/variants/265/370/card_image.webp",
"url": "https://www.mtggoldfish.com/price/apocalypse/135/dragon-arch"
},
{
"name": "Dragon Bell Monk",
"card_id": "Dragon Bell Monk [FRF]",
"set_code": "FRF",
"set": "Fate Reforged",
"collector_number": "10",
"finish": "regular",
"foil": false,
"variant": null,
"rarity": "Common",
"paper_price_usd": 0.2,
"online_price_tix": 0.03,
"image": "https://cards.mtggoldfish.com/images/019ce2ef-654b-7e20-90af-672d4eb54964/variants/265/370/card_image.webp",
"url": "https://www.mtggoldfish.com/price/fate-reforged/10/dragon-bell-monk"
}
]
}
}What the MTGGoldfish API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Cards whose name matches: one row per card name (the site's default printing) with tabletop USD and MTGO tix prices, rarity, set and url. `card` then gives every printing. | Pricing teams call search to get cards whose name matches. | query, set, sort, sort_direction, page |
| autocomplete | The site's type-ahead: up to 30 card printings (with exact card_id, set code, finish and url), card names, archetypes or tournaments for what has been typed so far. | Marketplace operators call autocomplete to get the site's type-ahead. | term, kind |
| card | One Magic printing in full: tabletop price in USD and MTGO price in tix, daily and weekly change, all-time high and low, spread, highest buylist, foil multiplier, vendor sell and buylist prices, every other printing, oracle text, legalities and images. | Catalog enrichment teams call card to get one Magic printing in full. | name, set, foil, card_id, url, ... |
| price_history | Every daily price of one printing since it was released, tabletop in USD and MTGO in tix, as two separate named series, with the site's own all-time high and low. | Retail analysts call price_history to get every daily price of one printing since it was released, tabletop in USD and MTGO in tix, as…. | name, set, foil, card_id, url, ... |
| sets | Every Magic set the site tracks: code, name, parent set and page url. | Pricing teams call sets to get every Magic set the site tracks. | query |
| set | All cards of one set with tabletop USD and MTGO tix prices, daily and weekly change in each market, rarity, collector number and finish; the set's sections and its total value. | Marketplace operators call set to get all cards of one set with tabletop USD and MTGO tix prices, daily and weekly change in each m…. | set, subset, limit, offset |
| set_history | Daily history of a whole set's total value, tabletop in USD and MTGO in tix: the same chart the set's page draws. | Catalog enrichment teams call set_history to get daily history of a whole set's total value, tabletop in USD and MTGO in tix. | set, subset_id, market, days |
| movers | Today's and this week's biggest price risers and fallers for a format or a set, in tabletop USD or MTGO tix. | Retail analysts call movers to get today's and this week's biggest price risers and fallers for a format or a set, in tabletop U…. | market, format, direction, period, limit |
| staples | The most played cards in a format: rank, percent of decks and average copies played, overall or by card type. | Pricing teams call staples to get the most played cards in a format. | format, category, limit |
| metagame | The metagame of a format: each archetype's share of the field, number of decks counted, tabletop and MTGO deck price and key cards, over 7 to 365 days, for tabletop or MTGO results. | Marketplace operators call metagame to get the metagame of a format. | format, market, period, page |
| archetype | One archetype's representative deck (cards, totals, event, date and source) and the most recent similar decks that made tournament results. | Catalog enrichment teams call archetype to get one archetype's representative deck (cards, totals, event, date and source) and the most rece…. | archetype |
| deck | A full decklist: name, author, event and placing, date, total price in USD and tix, card list with quantity and each card's unit price in both markets. | Retail analysts call deck to get a full decklist. | deck_id, include_prices |
| deck_search | Find decks by name, format, player, a card they contain (in the main deck, sideboard or as commander) and date range, among tournament results and user-submitted decks. | Pricing teams call deck_search to find decks by name, format, player, a card they contain (in the main deck, sideboard or as co…. | name, format, types, player, card, ... |
| tournaments | Tournaments (MTGO challenges, leagues, paper events) by name, format and date range, with the number of published decklists. | Marketplace operators call tournaments to get tournaments (MTGO challenges, leagues, paper events) by name, format and date range, with the…. | name, format, date_from, date_to, page |
| tournament | A tournament's standings: place, deck name and id, colors, pilot, and each deck's price in USD and tix. | Catalog enrichment teams call tournament to get a tournament's standings. | tournament |
| formats | The format names this API accepts. | Retail analysts call formats to get the format names this API accepts.. | none |
Call search from your stack
curl -X POST https://api.reefapi.com/mtggoldfish/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"dragon"}'import os
import requests
REEF_KEY = os.environ["REEF_KEY"]
r = requests.post(
"https://api.reefapi.com/mtggoldfish/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "dragon"
},
timeout=90,
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/mtggoldfish/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "dragon"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.mtggoldfish.search with {"query":"dragon"}.Who uses this API and why
- Track a card's price since release in USD or tix, or chart a whole set's total value
- Alert on the day's biggest risers and fallers for Modern, Standard or Pioneer
- Follow the metagame: which archetypes are gaining share, tabletop or MTGO, over 7 to 365 days
- Pull a tournament's decks with every card's price to see what a top list costs
- Compare Card Kingdom, TCGplayer and buylist numbers on a single card
Questions developers ask before integrating
How far back does the price history go?
Every daily price since the printing was released, as two separate series, tabletop in USD and MTGO in tix. Sheoldred, the Apocalypse returned 1,533 daily points from 2022-08-18 in our live test; Ragavan, Nimble Pilferer has 1,957 paper points from 2021-05-27. Pass days to keep only the most recent points.
Are paper and MTGO prices ever mixed?
No. Every price field names its currency: price_usd, price_tix, paper_price_usd, online_price_tix, or a series labelled currency USD or TIX. If a printing has no price in one market the field is null.
Can I get the metagame for tabletop as well as MTGO?
Yes. metagame takes market (paper or online) and period (7, 14, 30, 90 or 365 days). Each archetype comes with its share of the field, the number of decks counted, tabletop and MTGO deck price, colors and key cards, ready to pass as a slug to archetype.
Can I get a tournament's full decklists?
Yes. tournaments finds events by name, format and date, tournament returns the standings with place, deck name, pilot and each deck's price, and deck returns the full 75 with quantities, section, category and each card's price in USD and tix. On the deck we audited, the card prices added up exactly to the site's $629.52 total.
How do I find every printing of a card?
search returns one row per card name, in the site's default printing, which can be an MTGO-only one. card (with name, or name and set, or a card_id from search) returns printings: every other printing with its finish, variant and both prices (176 for Sol Ring). Pass any of those card_ids to card or price_history.
Which prices are shown on a card?
The site's tabletop and MTGO headline price, plus the vendor quotes it lists: Card Kingdom and TCGplayer Mid for tabletop, Cardhoarder for MTGO, and what buylists pay. Vendor links in the response point to the vendor's page without tracking parameters.
What is the MTGGoldfish API?
MTGGoldfish API is a ReefAPI endpoint group for magic: the gathering prices in usd and mtgo tix, daily price history, movers, metagame and decks. It returns live JSON through POST requests under /mtggoldfish/v1.
Is the MTGGoldfish API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. MTGGoldfish calls use the same shared credit balance as every other ReefAPI engine.
Do I need a MTGGoldfish login or account?
No login to MTGGoldfish is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the MTGGoldfish data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the MTGGoldfish API use?
MTGGoldfish actions currently cost 1-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call MTGGoldfish from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call mtggoldfish actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the MTGGoldfish API a MTGGoldfish scraper?
It is the managed alternative to a DIY MTGGoldfish scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same magic: the gathering prices in usd and mtgo tix, daily price history, movers, metagame and decks back as clean JSON.
Why does my MTGGoldfish scraper keep getting blocked?
Most MTGGoldfish scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked calls are free.