Mascus API & Scraper: parameters and responses
This is the reference for the 8 Mascus endpoints under /mascus/v1 (search, detail, categories, facets, suggest, brands, seller and seller_listings) and their 36 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 Mascus API turns the global used heavy-machinery marketplace into JSON in eight actions.
🤖 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 walks the whole catalogue with the filters the source itself honours: sector, category and sub-category, make and model, condition, advert type, year window, price band, hour-meter band, odometer band, engine output, gross weight, seller country and region, has-a-price, has-a-photo, has-a-video and listed-in-the-last-N-days, sorted by price, year, listing date, hours, odometer, make or country, up to 200 rows a page. detail returns one listing in full, including every technical property the dealer typed, each with the source's own label in your chosen language, a language-free field name and a parsed number and unit. categories returns all 676 taxonomy nodes with live counts, facets returns the source's own counts for every make, country, region, condition and advert type that has stock for your query, suggest turns a half-typed word into values the filters will actually match, brands returns the makes the marketplace itself promotes per sector, and seller and seller_listings cover the supply side. The field that makes this worth an API rather than a scraper is the price, because this marketplace runs about forty country front-ends and every one of them converts. The same John Deere S240 shows as 1,850 USD, 1,651 EUR, 1,400 GBP, 7,228 PLN, 604,144 HUF and 292,688 JPY depending on which front-end answers; price and currency here are always the seller's own asking price, verified identical across six front-ends and four requested currencies, and the conversion comes back under its own name. The odometer has the same problem and gets the same treatment: the international front-end reports miles and the other thirty-eight kilometres, so mileage_km is normalised on every market and the odometer filter is always taken in kilometres. One ReefAPI key, the standard { ok, data, meta, error } envelope, no Mascus account.
The same machine, read through six country front-ends
Listing gu7q6jaj is a 2021 John Deere S240 whose seller priced it at 1,850 USD. This is what each front-end displays, and what the API returns. Measured 2026-10-08.
| front-end | what the site displays | price / currency | price_converted |
|---|---|---|---|
| com (international) | 1,850 USD | 1850 USD | — (no conversion asked for) |
| de (Germany) | 1,651 EUR | 1850 USD | 1651 EUR |
| uk (United Kingdom) | 1,400 GBP | 1850 USD | 1400 GBP |
| pl (Poland) | 7,228 PLN | 1850 USD | 7228 PLN |
| hu (Hungary) | 604,144 HUF | 1850 USD | 604144 HUF |
| jp (Japan) | 292,688 JPY | 1850 USD | 292688 JPY |
Ten readings of the same listing across six front-ends and four requested currencies returned exactly one price and currency pair: 1850 USD. Publishing the displayed number instead would make the same machine 1,850 or 604,144 depending on which host answered — a 326x error in a field that is always filled and always plausible.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/mascus/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "excavator",
"market": "com",
"currency": "EUR",
"page": 1,
"page_size": 40
}
}{
"ok": true,
"meta": {
"api": "mascus",
"endpoint": "search",
"mode": "live",
"latency_ms": 437.6,
"record_count": 40,
"bytes": 69277,
"cache_hit": false,
"total": 46575,
"price_filter_currency": "EUR",
"market": "com",
"odometer_unit_on_this_market": "mi",
"filters_applied": {
"query": "excavator"
},
"pagination": {
"page": 1,
"page_size": 40,
"last_page": 250,
"retrievable_max": 10000,
"has_more": true
},
"source_search_title": "excavator",
"warnings": [
"this query matches 46,575 listings but only the first 10,000 are retrievable; narrow it with a filter rather than paging, because past that ceiling the source re-serves page 1"
],
"charged_credits": 3,
"version": "1.0.0",
"request_id": "c5230a17609f4c25",
"queue_ms": 1.6,
"fetched_at": "2026-10-31T13:02:54.696Z"
},
"data": {
"listings": [
{
"listing_id": "E3A7485B",
"asset_id": "hidm7n8q",
"url": "https://www.mascus.com/construction/mini-diggers-excavators-7/john-deere-35-p/hidm7n8q.html",
"listing_type": "classified",
"brand": "John Deere",
"model": "35 P",
"year": 2024,
"catalog": "construction",
"category": "miniexcavators",
"operating_hours": 12,
"operating_hours_unit": "h",
"mileage": null,
"mileage_unit": null,
"mileage_km": null,
"mileage_km_exact": null,
"price": 55000,
"currency": "USD",
"price_on_request": false,
"price_eur": 48945,
"price_converted": 48945,
"price_converted_currency": "EUR",
"location_city": "Indianapolis, Indiana",
"location_country_code": "US",
"seller": {
"dealer_id": "C349AC7F",
"name": "West Side Tractor Sales Co.- Indianapolis",
"country": "US",
"url": "https://www.mascus.com/west-side-tractor-sales-co-indianapolis/c349ac7f,1,relevance,searchdealer.html"
},
"image": "https://dnge9sb91helb.cloudfront.net/image/product/medium/johndeereus/john-deere-35-p,10141437_80520025_65726.jpg",
"image_count": 22,
"video_count": 0,
"featured": false,
"highlighted": false,
"listed_last_24h": true,
"listed_at": "2026-10-31T03:15:24.54"
},
{
"listing_id": "5060C15D",
"asset_id": "8f9ffg8s",
"url": "https://www.mascus.com/construction/mini-diggers-excavators-7/bobcat-e20/8f9ffg8s.html",
"listing_type": "auction",
"brand": "Bobcat",
"model": "E20",
"year": 2016,
"catalog": "construction",
"category": "miniexcavators",
"operating_hours": 1366,
"operating_hours_unit": "h",
"mileage": null,
"mileage_unit": null,
"mileage_km": null,
"mileage_km_exact": null,
"price": null,
"currency": "USD",
"price_on_request": true,
"price_eur": null,
"location_city": "Perris, California",
"location_country_code": "US",
"seller": {
"dealer_id": "7D1826F8",
"name": "Ritchie Bros Los Angeles",
"country": "US",
"url": "https://www.mascus.com/ritchie-bros-los-angeles/7d1826f8,1,relevance,searchdealer.html"
},
"image": "https://dnge9sb91helb.cloudfront.net/image/product/medium/rbauctionusatwo/bobcat-e20,b5044be3c08d48ea.jpg",
"image_count": 32,
"video_count": 0,
"featured": false,
"highlighted": false,
"listed_last_24h": false,
"listed_at": "2026-10-31T02:08:37",
"auction": {
"event_name": "California Regional Auction, USA - Nov 04, 2026",
"starts_at": "2026-11-04T18:00:00",
"ends_at": "2026-11-06T05:00:00",
"country": "US",
"city": "Perris, CA",
"lot_url": "https://www.rbauction.com/pdp/2016-bobcat-e20-excavators/16205765",
"auction_house_listing_id": "85A5B245-39F6-407D-B67B-8B86DCB9226E"
}
},
{
"listing_id": "E9B63DF5",
"asset_id": "hoel6sik",
"url": "https://www.mascus.com/construction/crawler-excavators/cat-335fl-cr-tracked-excavator/hoel6sik.html",
"listing_type": "auction",
"brand": "CAT",
"model": "335FL CR Tracked Excavator",
"year": 2018,
"catalog": "construction",
"category": "crawlerexcavators",
"operating_hours": 3313,
"operating_hours_unit": "h",
"mileage": null,
"mileage_unit": null,
"mileage_km": null,
"mileage_km_exact": null,
"price": null,
"currency": "USD",
"price_on_request": true,
"price_eur": null,
"location_city": "Perris, California",
"location_country_code": "US",
"seller": {
"dealer_id": "7D1826F8",
"name": "Ritchie Bros Los Angeles",
"country": "US",
"url": "https://www.mascus.com/ritchie-bros-los-angeles/7d1826f8,1,relevance,searchdealer.html"
},
"image": "https://dnge9sb91helb.cloudfront.net/image/product/medium/rbauctionusatwo/cat-335fl-cr-tracked-e,5dbd37c9d22249ae.jpg",
"image_count": 30,
"video_count": 0,
"featured": false,
"highlighted": false,
"listed_last_24h": false,
"listed_at": "2026-10-31T02:08:34",
"auction": {
"event_name": "California Regional Auction, USA - Nov 04, 2026",
"starts_at": "2026-11-04T18:00:00",
"ends_at": "2026-11-06T05:00:00",
"country": "US",
"city": "Perris, CA",
"lot_url": "https://www.rbauction.com/pdp/2018-cat-335flcrtrackedexcavator-excavators/16147196",
"auction_house_listing_id": "5E40291E-7732-404C-A8EE-69F7B8C31F62"
}
}
]
}
}What the Mascus API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search or browse the whole marketplace. Combine a keyword with any of the typed filters the source supports natively — sector, category, sub-category, make, model, condition, advert type, year window, price band, hour-meter band, odometer band, engine output, gross weight, seller country and region, has-a-price, has-a-photo, has-a-video, listed-in-the-last-N-days — and sort by price, year, listing date, hours, odometer, make or country. Up to 200 rows a page. 🔴 Two things worth knowing before you build a loop: only the first 10,000 rows of any query are retrievable (past that the source silently re-serves page 1, so this endpoint refuses the call instead), and `price`/`currency` are the seller's own asking price — NOT the number the country front-end displays, which is a live conversion and differs by up to 326x between front-ends for the same machine. | Pricing teams call search to search or browse the whole marketplace. | market, currency, query, catalog, category, ... |
| detail | One listing in full, by id or URL. Returns the machine (make, model, model group, year, category path, hour meter, odometer normalised to kilometres), the price block (the seller's own asking price and currency, the EUR equivalent, the VAT rate, whether a price is published at all, and the source's own printed price rows), every technical property the seller typed — each with the source's own label in your chosen language, a language-free field name, and a parsed number and unit where there is one — the accessories list, the seller's free-text description in each language they wrote it in, the auction event with its bidding deadline and the auction house's own lot id, the rental day/week/month rates with and without VAT and the regions it can be hired in, the machine's own town, region, postcode, country and map coordinates, the dealer's business address and years on the marketplace, the finance/insurance/transport services offered, the full-size gallery and any videos, and the category breadcrumb. | Marketplace operators call detail to get one listing in full, by id or URL. | asset_id, url, market |
| categories | The marketplace's own taxonomy with live per-node listing counts: six sectors (construction 252,476 · transport 96,956 · agriculture 83,644 · material handling 27,455 · forestry 25,707 · groundcare 10,840) and, under each, the categories and sub-categories with the exact codes every other action's `category` and `subcategory` filters take. Pass a `category_code` to get one sector's sub-tree. Every count is the source's own live figure. 🔴 The filter code and the source's URL slug differ on three of the six sectors, so this is the action to read codes from rather than lifting them out of a URL. | Catalog enrichment teams call categories to get the marketplace's own taxonomy with live per-node listing counts. | market, category_code |
| facets | The source's own live filter counts for a query: which makes, countries, regions, categories, conditions, advert types, accessories and emission levels have stock and how much of it. This is how you learn the exact spelling a filter wants (the source wants 'CAT', not 'Caterpillar', and region NAMES rather than codes) and how to split a query that is deeper than the 10,000-row retrievable ceiling. Every group says in `value_kind` whether its values are names, ISO codes or the source's own numeric property ids — the ids are what the filter takes, so they are published as they are rather than guessed at. | Retail analysts call facets to get the source's own live filter counts for a query. | market, currency, query, catalog, category, ... |
| suggest | The marketplace's own type-ahead for whatever a user has typed, in one list where every entry is tagged with its kind: make, model, model group, category (with the code the `category`/`subcategory` filters take) and dealer (with the id the `seller` action takes). Use it to turn free text into values the filters will actually match, instead of guessing a spelling the source answers with zero rows. | Pricing teams call suggest to get the marketplace's own type-ahead for whatever a user has typed, in one list where every entry…. | query, market |
| brands | The makes the marketplace itself promotes per sector, with a live listing count each — the source's own shortlist of the biggest manufacturers in construction, transport, agriculture, material handling, forestry and groundcare. A cheap, single-call answer to 'what is actually traded here and in what volume'. For the COMPLETE make list of a specific query, including the long tail, use `facets` and read its `brand` group. | Marketplace operators call brands to get the makes the marketplace itself promotes per sector, with a live listing count each. | market |
| seller | One dealer's public business profile by id: company name, postal address (street, postcode, town, region, country), visiting address where they publish one, website, logo, their own description of the business, the makes they list themselves under, their branch outlets, map coordinates, and how long they have traded on this marketplace with the date that count runs from. 🔴 The source also returns a named salesperson, a direct e-mail, a mobile and a switchboard number on this object; none of it is returned here on any action. Use `seller_listings` for this dealer's stock. | Catalog enrichment teams call seller to get one dealer's public business profile by id. | dealer_id, market |
| seller_listings | One dealer's full stock, as rows identical to `search`, with every `search` filter and sort available on top. 🔴 This is the action the source makes easiest to get wrong: handing its dealer filter the complete GUID answers HTTP 200 with 125 rows from FOUR different companies, because the GUID's middle segment is shared. This endpoint sends only the short id the source's own dealer links use, and then checks that what came back really belongs to one company before returning it — if it does not, you get an error rather than four dealers' machines labelled as one. | Retail analysts call seller_listings to get one dealer's full stock, as rows identical to `search`, with every `search` filter and sort a…. | dealer_id, market, currency, query, catalog, ... |
Call search from your stack
curl -X POST https://api.reefapi.com/mascus/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"excavator","market":"com","currency":"EUR","page":1,"page_size":40}'import os
import requests
REEF_KEY = os.environ["REEF_KEY"]
r = requests.post(
"https://api.reefapi.com/mascus/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "excavator",
"market": "com",
"currency": "EUR",
"page": 1,
"page_size": 40
},
timeout=90,
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/mascus/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "excavator",
"market": "com",
"currency": "EUR",
"page": 1,
"page_size": 40
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.mascus.search with {"query":"excavator","market":"com","currency":"EUR","page":1,"page_size":40}.Who uses this API and why
- Price a machine before you buy or sell it: narrow one make and model to a year window and an hour-meter band and you have the live comparable set — and because price is the seller's own currency on every row, the comparables are comparable without you unwinding six exchange rates first.
- Source stock across 80 countries: filter by seller country and region, condition, price band, auction-only or rental-only, then pull the dealer behind any row with seller, or their whole inventory with seller_listings.
- Watch a segment: sort by newest listing, poll a narrow query with listed_within_days, and read the auction wing's bidding deadlines straight off the rows that have them.
- Build a filter UI without guessing a spelling: facets returns the source's own live counts for every make, country, region, condition and advert type that has stock for your query, with value_kind saying whether each group's values are names, ISO codes or the source's own property ids, and suggest maps whatever a user typed onto values the filters will match.
- Track the market's shape: categories returns all 676 taxonomy nodes with live per-node counts in one call, which is how you see 252,476 construction machines split into 40,078 excavators and 20,810 crawler excavators.
Questions developers ask before integrating
Which price does the API return, and does it change with the market?
It returns the seller's own asking price in the seller's own currency, and it does not change. That matters because the marketplace itself does change it: the same John Deere S240 displays as 1,850 USD on the international front-end and 1,651 EUR, 1,400 GBP, 7,228 PLN, 604,144 HUF and 292,688 JPY on the others. Read across six front-ends and four requested currencies, price and currency came back as 1850 USD every single time. The conversion is still there when you want it, as price_eur and as price_converted with price_converted_currency beside it, so it can never be mistaken for the asking price.
Is the odometer in kilometres or miles?
mileage_km is always kilometres, on every market. The source is not: a Kubota M5-111D reads 1,972 mil on the international front-end and 3,173 km on all thirty-eight others, the same machine. mileage and mileage_unit give you the reading as that front-end published it, and mileage_km_exact tells you when the normalised value is a back-conversion rather than the stored number, because the source stores kilometres and rounds them to whole miles for one host. The odometer filter, mileage_km_min and mileage_km_max, is always taken in kilometres and converted before the request leaves — the same 0 to 100,000 band answers 9,811 rows on one front-end and 7,051 on another if you send it raw.
How many rows can I get for one query?
10,000, at any page size, and the API refuses the call that would go past it rather than letting you page into nothing. This is the one limit worth knowing before you build a loop: past 10,000 the source answers HTTP 200 and serves page 1's rows under the page number you asked for, which was measured at four different page sizes. pagination.retrievable_max is 10,000, has_more is honest, and page_size goes to 200 so the ceiling is 50 calls away rather than 250. The way deeper is to narrow, and all 22 filters were measured to bite.
Is the hour meter the same field as the odometer?
No, and keeping them apart is deliberate. operating_hours is the hour meter, mileage is the odometer, and this source publishes one or the other per machine, never both — excavators and tractors carry hours, trucks and vans carry an odometer. Comparing a 9,110 to a 161,190 because they sat in one field would be the easiest wrong answer on this marketplace. The hour meter is also the one reading the source does not convert: the 0 to 2,000 hour band answers the same 412 rows on every front-end.
Why do so many listings have no price?
Because about half of this marketplace is auction lots and price-on-request dealer stock. Measured over 700 rows from 14 different queries, 337 had no price. That is returned as a state and not as a gap: price_on_request is true, price is null, and the currency is still published because the source does know which currency the machine would have been priced in. A price of 0 on this source means the same thing as null, which is why neither is ever returned as a number. Set with_price if you only want priced comparables; that alone takes a 46,041-row query to 32,308.
What happens if I send a filter value or a filter name the source does not know?
You get a clear error instead of the wrong answer. Three of this source's filter names and two of its value sets are accepted with HTTP 200 and then silently ignored, which returns the whole unfiltered catalogue looking filtered — a year window built the obvious way is one of them. So every enum and every parameter name is checked before the request leaves, and anything this endpoint does not know is reported in meta.warnings rather than forwarded. Where the source IS honest, it is left alone: an unknown make or country is answered with zero rows, and that is passed through as the answer it is.
Which markets are supported, and do they share one catalogue?
39 country front-ends, and yes — one shared catalogue, so market picks the language the labels come back in and nothing about the inventory. Each of the 39 was verified by loading a real listing on that host and confirming its label vocabulary came back populated. Three front-ends the marketplace itself links, mascus.fr, mascus.es and mascus.com.br, serve their home page but answer HTTP 404 for every listing, checked repeatedly; they return MARKET_UNAVAILABLE rather than a half-filled answer.
Can I get one dealer's whole inventory?
Yes, with seller_listings, and it is checked before it is returned. This is the action the source makes easiest to get wrong: handing its dealer filter the complete GUID answers HTTP 200 with 125 rows from four different companies, because the GUID's middle segment is shared between them. The endpoint sends only the short dealer id the source's own links use and then asserts that every row it got back really belongs to one company — if it does not, you get an error rather than four dealers' machines labelled as one. seller returns that dealer's business profile beside it.
What do I get about the dealer, and what is left out?
Business facts and nothing personal: company name, street, postcode, town, region, country, visiting address where they publish one, website, logo, their own description, branch outlets, coordinates and how many years they have traded on the marketplace with the date that count runs from. The source also returns a named salesperson, a direct e-mail, a mobile and a switchboard number on the same records; none of them is returned by any action here. The one thing passed through verbatim is the seller's own advert text, which is the machine's description and occasionally has a phone number typed into it by the dealer.
How fast is it, and how reliable?
One request to the source per call, with a median of 631 ms and a 95th percentile of 1.5 s. A run across all eight actions and six different front-ends was 20 of 20.
Does a free-text search give the same results on every market?
No, and this is worth knowing if you need reproducibility. Free text is scored in the chosen front-end's own language, so the same word is a different query per market: 'excavator' answered 46,041 rows on the international front-end and 46,118 on the German one, and the first 40 rows of the two answers had not one listing in common. A make-and-model query such as 'Kubota M5-111D' does match identically on both. Pin a result set you need to reproduce with the typed filters or a dealer id, not with a word.
What is the Mascus API?
Mascus API is a ReefAPI endpoint group for the global used heavy-machinery marketplace as json: ~497,000 live listings of construction plant, trucks, agricultural and forestry machines from dealers in 80 countries, each with the seller's own asking price in the seller's own currency — not the number the country front-end converts it into. It returns live JSON through POST requests under /mascus/v1.
Is the Mascus API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Mascus calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Mascus login or account?
No login to Mascus 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.