Reef AI: ask for any data. Try it
This page is the Otomoto parameter reference. What the data is used for, a real sample and pricing are on Otomoto API: what you get →
Classifieds & Second-hand

Otomoto API & Scraper: parameters and responses

This is the reference for the 3 Otomoto endpoints under /otomoto/v1 (search, listing/detail and makes) and their 24 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.

Otomoto API returns live Otomoto data as clean JSON for otomoto The primary endpoint, search, returns matching records including ad id, listing id, eg id6igtyl or olx id6iguof this is what listingdetail takes, title and subtitle.

3 actionsLive JSON1,000 free credits$0.67–$1.50 / 1,000 creditsMCP-ready
Get a free keyOpen in playground

🤖 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.

Developers reach for it when they need to read second-hand listings, asking prices, seller inventory and country-specific listing ids without maintaining one-off scraping code or separate API contracts. If you were about to build or fix a Otomoto scraper, this API is the maintained alternative — it returns the same data as clean JSON, with the proxies, rotation and anti-bot handling already solved. This page covers the live example, request shape, response shape and available actions: search, listing/detail, makes. Every request uses the same ReefAPI envelope, one API key and one shared credit pool, so it fits alongside the rest of your data stack.

Live example

Real request and response JSON

Captured from the indexed primary action, search, on .

Captured request
{
  "method": "POST",
  "url": "https://api.reefapi.com/otomoto/v1/search",
  "headers": {
    "x-api-key": "$REEF_KEY",
    "content-type": "application/json"
  },
  "body": {
    "make": "bmw"
  }
}
Captured response
{
  "ok": true,
  "meta": {
    "api": "otomoto",
    "endpoint": "search",
    "mode": "live",
    "latency_ms": 1867.6,
    "record_count": 32,
    "bytes": 1599968,
    "cache_hit": false,
    "country": "pl",
    "requests": 1,
    "total_results": 21321,
    "page": 1,
    "charged_credits": 1,
    "version": "0.1.1",
    "request_id": "6705e5a06dc345b0",
    "queue_ms": 1.7,
    "fetched_at": "2026-11-03T17:32:10.848Z"
  },
  "data": {
    "results": [
      {
        "ad_id": "6151476804",
        "listing_id": "ID6IiY7O",
        "title": "BMW Seria 3 330i Edition M Sport Shadow",
        "subtitle": "BMW 330i xDrive 2020 | 2.0 Turbo | Automat | M Sport Shadow",
        "url": "https://www.otomoto.pl/osobowe/oferta/bmw-seria-3-ID6IiY7O.html",
        "created_at": "2026-11-02T14:42:02Z",
        "price": 59000,
        "price_raw": "59000",
        "currency": "PLN",
        "price_is_gross": true,
        "price_mismatch": null,
        "price_evaluation": "NONE",
        "price_drop": null,
        "make": "BMW",
        "make_slug": "bmw",
        "model": "Seria 3",
        "model_slug": "seria-3",
        "version": "330i Edition M Sport Shadow",
        "year": 2020,
        "mileage_km": 31500,
        "mileage_display": "31500 km",
        "fuel_type": {
          "value": "petrol",
          "label": "Benzyna"
        },
        "gearbox": {
          "value": "automatic",
          "label": "Automatyczna"
        },
        "engine_power_hp": 252,
        "engine_capacity_ccm": 1998,
        "field_mismatch": null,
        "location": {
          "city": "Warszawa",
          "region": "Mazowieckie",
          "country": "PL"
        },
        "seller": {
          "kind": "dealer",
          "uuid": "a99f9b81-027b-415c-a321-85390571359c",
          "dealer_id": "18253685",
          "dealer_name": "Pan America",
          "dealer_url": "https://panamerica.otomoto.pl",
          "is_credit_intermediary": false
        },
        "is_promoted": true,
        "promotions": [
          "topads",
          "export_olx"
        ],
        "badges": null,
        "cepik_verified": false,
        "image": "https://ireland.apollo.olxcdn.com/v1/files/ct458hegoimn-OTOMOTOPL/image;s=640x480",
        "category_id": "29"
      },
      {
        "ad_id": "6151500962",
        "listing_id": "ID6Ij4ps",
        "title": "BMW Seria 3 330i xDrive M Sport",
        "subtitle": null,
        "url": "https://www.otomoto.pl/osobowe/oferta/bmw-seria-3-ID6Ij4ps.html",
        "created_at": "2026-11-03T13:20:01Z",
        "price": 38900,
        "price_raw": "38900",
        "currency": "PLN",
        "price_is_gross": true,
        "price_mismatch": null,
        "price_evaluation": "NONE",
        "price_drop": null,
        "make": "BMW",
        "make_slug": "bmw",
        "model": "Seria 3",
        "model_slug": "seria-3",
        "version": "330i xDrive M Sport",
        "year": 2021,
        "mileage_km": 41886,
        "mileage_display": "41886 km",
        "fuel_type": {
          "value": "petrol",
          "label": "Benzyna"
        },
        "gearbox": {
          "value": "automatic",
          "label": "Automatyczna"
        },
        "engine_power_hp": 252,
        "engine_capacity_ccm": 1998,
        "field_mismatch": null,
        "location": {
          "city": "Kraków",
          "region": "Małopolskie",
          "country": "PL"
        },
        "seller": {
          "kind": "private",
          "uuid": "72556414-1041-70bd-3797-3b564c87ea9f",
          "dealer_id": "18918328",
          "dealer_name": null,
          "dealer_url": null,
          "is_credit_intermediary": null
        },
        "is_promoted": false,
        "promotions": [
          "highlight",
          "export_olx"
        ],
        "badges": null,
        "cepik_verified": false,
        "image": "https://ireland.apollo.olxcdn.com/v1/files/imvdwupizxqi-OTOMOTOPL/image;s=640x480",
        "category_id": "29"
      },
      {
        "ad_id": "6151509604",
        "listing_id": "ID6Ij6EQ",
        "title": "BMW Seria 5 530i xDrive GPF Luxury Line sport",
        "subtitle": "BMW Seria 5 530i xDrive Luxury Line Sport",
        "url": "https://www.otomoto.pl/osobowe/oferta/bmw-seria-5-ID6Ij6EQ.html",
        "created_at": "2026-11-03T17:09:40Z",
        "price": 56900,
        "price_raw": "56900",
        "currency": "PLN",
        "price_is_gross": true,
        "price_mismatch": null,
        "price_evaluation": "NONE",
        "price_drop": null,
        "make": "BMW",
        "make_slug": "bmw",
        "model": "Seria 5",
        "model_slug": "seria-5",
        "version": "530i xDrive GPF Luxury Line sport",
        "year": 2019,
        "mileage_km": 87093,
        "mileage_display": "87093 km",
        "fuel_type": {
          "value": "petrol",
          "label": "Benzyna"
        },
        "gearbox": {
          "value": "automatic",
          "label": "Automatyczna"
        },
        "engine_power_hp": 252,
        "engine_capacity_ccm": 1998,
        "field_mismatch": null,
        "location": {
          "city": "Warszawa",
          "region": "Mazowieckie",
          "country": "PL"
        },
        "seller": {
          "kind": "dealer",
          "uuid": "a99f9b81-027b-415c-a321-85390571359c",
          "dealer_id": "18253685",
          "dealer_name": "Pan America",
          "dealer_url": "https://panamerica.otomoto.pl",
          "is_credit_intermediary": false
        },
        "is_promoted": true,
        "promotions": [
          "topads",
          "export_olx"
        ],
        "badges": null,
        "cepik_verified": false,
        "image": "https://ireland.apollo.olxcdn.com/v1/files/41jnaysxyo502-OTOMOTOPL/image;s=640x480",
        "category_id": "29"
      }
    ],
    "count": 32,
    "total_results": 21321,
    "total_pages": 667,
    "page": 1,
    "page_size": 32,
    "has_more": true,
    "sort": "relevance",
    "sort_id": "relevance_web",
    "filters_applied": {
      "category_id": {
        "value": "29",
        "canonical": "osobowe",
        "labels": [
          "Osobowe"
        ]
      },
      "filter_enum_make": {
        "value": "bmw",
        "canonical": "bmw",
        "labels": [
          "BMW"
        ]
      }
    },
    "breadcrumb": [
      {
        "label": "Strona główna",
        "url": "https://www.otomoto.pl"
      },
      {
        "label": "Osobowe",
        "url": "https://www.otomoto.pl/osobowe"
      },
      {
        "label": "BMW",
        "url": "https://www.otomoto.pl/osobowe/bmw"
      }
    ],
    "related_links": {
      "gearboxes": [
        {
          "title": "BMW Automatyczna",
          "url": "https://www.otomoto.pl/osobowe/bmw?search%5Bfilter_enum_gearbox%5D=automatic",
          "slug": "bmw",
          "count": 17184
        },
        {
          "title": "BMW Manualna",
          "url": "https://www.otomoto.pl/osobowe/bmw?search%5Bfilter_enum_gearbox%5D=manual",
          "slug": "bmw",
          "count": 4132
        }
      ],
      "models": [
        {
          "title": "BMW Seria 3",
          "url": "https://www.otomoto.pl/osobowe/bmw/seria-3",
          "slug": "seria-3",
          "count": 4153
        },
        {
          "title": "BMW Seria 5",
          "url": "https://www.otomoto.pl/osobowe/bmw/seria-5",
          "slug": "seria-5",
          "count": 3708
        },
        {
          "title": "BMW X3",
          "url": "https://www.otomoto.pl/osobowe/bmw/x3",
          "slug": "x3",
          "count": 2223
        }
      ],
      "fuel-types": [
        {
          "title": "BMW Diesel",
          "url": "https://www.otomoto.pl/osobowe/bmw?search%5Bfilter_enum_fuel_type%5D=diesel",
          "slug": "bmw",
          "count": 11345
        },
        {
          "title": "BMW Benzyna",
          "url": "https://www.otomoto.pl/osobowe/bmw?search%5Bfilter_enum_fuel_type%5D=petrol",
          "slug": "bmw",
          "count": 8815
        },
        {
          "title": "BMW Hybryda Plug-in",
          "url": "https://www.otomoto.pl/osobowe/bmw?search%5Bfilter_enum_fuel_type%5D=plugin-hybrid",
          "slug": "bmw",
          "count": 570
        }
      ],
      "model-generations": [
        {
          "title": "BMW Seria 3 G20/G21 (2019-)",
          "url": "https://www.otomoto.pl/osobowe/bmw/seria-3?search%5Bfilter_enum_generation%5D=gen-g20-2019",
          "slug": "seria-3",
          "count": 1318
        },
        {
          "title": "BMW Seria 5 G30/G31 (2017-2023)",
          "url": "https://www.otomoto.pl/osobowe/bmw/seria-5?search%5Bfilter_enum_generation%5D=gen-g30-2017",
          "slug": "seria-5",
          "count": 1026
        },
        {
          "title": "BMW Seria 3 E90/E91/E92/E93 (2005-2012)",
          "url": "https://www.otomoto.pl/osobowe/bmw/seria-3?search%5Bfilter_enum_generation%5D=gen-e90-2005-2012",
          "slug": "seria-3",
          "count": 1000
        }
      ],
      "regions": [
        {
          "title": "BMW Mazowieckie",
          "url": "https://www.otomoto.pl/osobowe/bmw/mazowieckie",
          "slug": "mazowieckie",
          "count": 4594
        },
        {
          "title": "BMW Śląskie",
          "url": "https://www.otomoto.pl/osobowe/bmw/slaskie",
          "slug": "slaskie",
          "count": 2774
        },
        {
          "title": "BMW Wielkopolskie",
          "url": "https://www.otomoto.pl/osobowe/bmw/wielkopolskie",
          "slug": "wielkopolskie",
          "count": 2596
        }
      ],
      "body-types": [
        {
          "title": "BMW SUV",
          "url": "https://www.otomoto.pl/osobowe/bmw/seg-suv",
          "slug": "seg-suv",
          "count": 6592
        },
        {
          "title": "BMW Sedan",
          "url": "https://www.otomoto.pl/osobowe/bmw/seg-sedan",
          "slug": "seg-sedan",
          "count": 5648
        },
        {
          "title": "BMW Kombi",
          "url": "https://www.otomoto.pl/osobowe/bmw/seg-combi",
          "slug": "seg-combi",
          "count": 4436
        }
      ]
    },
    "search_url": "https://www.otomoto.pl/osobowe/bmw?search%5Border%5D=relevance_web",
    "category": "osobowe",
    "currency": "PLN"
  }
}
Actions

What the Otomoto API does

ActionDescriptionConcrete use caseKey params
searchSearch otomoto.pl the way its own visitors do: pick a section (cars, vans, motorcycles), narrow by make and model, by voivodeship or by city with a radius, and apply otomoto's own price, year, mileage, engine power, engine capacity, fuel, gearbox, body, condition, damage and seller-type filters. Every ad comes back with the price in PLN cross-checked against otomoto's own price string, the published model year, the odometer reading with the site's own formatted string beside it, fuel and gearbox in both otomoto's code and its Polish label, engine power and capacity, the city and voivodeship, whether a private person or a dealer is selling (otomoto's own flag, never inferred), otomoto's below/at/above-market price indicator, the CEPiK history-check flag, and whether the ad is a paid promoted placement. Promoted ads are returned in the position otomoto gives them and flagged, never dropped. Sort by price, mileage, engine power or posting date, and page through the whole result set. The answer repeats every filter otomoto actually applied, with the canonical slug it resolved to, and lists every model otomoto publishes for the chosen make with its live ad count — so the next call can drill down without guessing a slug.Price-intelligence teams call search to search otomoto.pl the way its own visitors do.category, make, model, location, distance_km, ...
listing/detailThe full otomoto offer record from an offer URL or its ID token: title, the price in PLN with otomoto's own VAT and invoice labels, the seller's type (private person or dealer), the dealer's trading name, page and how many ads it currently has, the city, voivodeship and country, the whole published specification grouped exactly as otomoto groups it (basic information, technical specification, condition and history, financing), every equipment item by category, every photo at full size, the seller's own description with its HTML stripped, the CEPiK history-check flag, the posting and last-update timestamps, the ad status, and whether the ad carries a paid promotion. Numbers otomoto publishes twice — mileage, year, engine power, engine capacity — are returned only when the site's own formatted string agrees with its raw value. The seller's street address, postcode, map point and website are returned as the page carries them; the phone number sits behind otomoto's reveal call and is not requested. A withdrawn or unknown offer answers NOT_FOUND.Classifieds aggregators call listing/detail to get the full otomoto offer record from an offer URL or its ID token.listing
makesThe makes otomoto itself lists on a section's landing page, ranked by how many live ads each one carries, with the exact slug a search needs. This is otomoto's own published shortlist, not its full make register — it is as long as otomoto makes it (20 entries on the cars section, measured), and `count` says how many came back. Use it to get a slug right before searching, because otomoto silently ignores a make it does not recognise and answers with the whole section instead. Passing a make returns that make's model shortlist instead, each model with its slug and live ad count.Resale and arbitrage tools call makes to get the makes otomoto itself lists on a section's landing page, ranked by how many live ads each….category, make
Code samples

Call search from your stack

curl -X POST https://api.reefapi.com/otomoto/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"make":"bmw"}'
MCP one-liner
Ask your MCP-connected assistant: call reefapi.otomoto.search with {"make":"bmw"}.
Use cases

Who uses this API and why

  • Price-intelligence teams use Otomoto to search otomoto.pl the way its own visitors do.
  • Classifieds aggregators use Otomoto to get the full otomoto offer record from an offer URL or its ID token.
  • Resale and arbitrage tools use Otomoto to get the makes otomoto itself lists on a section's landing page, ranked by how many live ads each….
FAQ

Questions developers ask before integrating

What is the Otomoto API?

Otomoto API is a ReefAPI endpoint group for otomoto It returns live JSON through POST requests under /otomoto/v1.

Is the Otomoto API free to try?

Yes. ReefAPI starts with 1,000 free credits, no card required. Otomoto calls use the same shared credit balance as every other ReefAPI engine.

Do I need an Otomoto login or account?

No login to Otomoto 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 Otomoto 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 Otomoto API use?

Otomoto actions currently cost 1 credit per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.

Can I call Otomoto from an AI assistant or MCP client?

Yes. Connect ReefAPI once through MCP and your assistant can call otomoto actions with the same key, credit pool and JSON envelope used by normal REST requests.

Is the Otomoto API an Otomoto scraper?

It is the managed alternative to a DIY Otomoto 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 otomoto back as clean JSON.

Why does my Otomoto scraper keep getting blocked?

Most Otomoto 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.

docs / otomoto

Otomoto

Otomoto

base /otomoto/v13 endpoints
post/otomoto/v1/listing/detail1 credit

The full otomoto offer record from an offer URL or its ID token: title, the price in PLN with otomoto's own VAT and invoice labels, the seller's type (private person or dealer), the dealer's trading name, page and how many ads it currently has, the city, voivodeship and country, the whole published specification grouped exactly as otomoto groups it (basic information, technical specification, condition and history, financing), every equipment item by category, every photo at full size, the seller's own description with its HTML stripped, the CEPiK history-check flag, the posting and last-update timestamps, the ad status, and whether the ad carries a paid promotion. Numbers otomoto publishes twice — mileage, year, engine power, engine capacity — are returned only when the site's own formatted string agrees with its raw value. The seller's street address, postcode, map point and website are returned as the page carries them; the phone number sits behind otomoto's reveal call and is not requested. A withdrawn or unknown offer answers NOT_FOUND.

ParameterAllowed / rangeDescription
listingrequired—An otomoto offer URL, or the listing_id at the end of it (…-ID6IgtYL.html → ID6IgtYL; an ad cross-posted from OLX ends …-OLX_ID6IguOF.html → OLX_ID6IguOF, and the OLX_ part is required). Search rows carry both `url` and `listing_id`. The numeric `ad_id` is otomoto's internal id and does NOT address an offer page; passing it is refused rather than reported as missing.
Try in playground →
post/otomoto/v1/makes1 credit

The makes otomoto itself lists on a section's landing page, ranked by how many live ads each one carries, with the exact slug a search needs. This is otomoto's own published shortlist, not its full make register — it is as long as otomoto makes it (20 entries on the cars section, measured), and `count` says how many came back. Use it to get a slug right before searching, because otomoto silently ignores a make it does not recognise and answers with the whole section instead. Passing a make returns that make's model shortlist instead, each model with its slug and live ad count.

ParameterAllowed / rangeDescription
category = osoboweoptionalosobowe · dostawcze · motocykle-i-quadyWhich otomoto section to search. These are otomoto's own URL sections; the category id each one resolves to is returned in filters_applied.
makeoptional—A make exactly as otomoto spells it in its own URLs: bmw, audi, volkswagen, mercedes-benz, skoda. Case and spaces are normalised. If otomoto does not recognise the make the call is refused — it is NOT quietly widened to every car, which is what the site itself does.
Try in playground →
Built for volume
5M+ requests a day

Measured at 60 requests a second across the fleet, with no central bottleneck. Volume pricing is on request, and per-key limits are raised for high-volume accounts.

Missing a source?
We build it

Tell us a site we do not cover yet and it becomes an engine. A customer asked for bestprice.gr on a Sunday and it was in the catalog the next day.

Support
2 minute median reply

Median time from a question in the live chat to the first answer, measured across every answered conversation. Setup help included, no support tier to buy.

One key, one balance
Every API included

No per-site plans and no separate subscriptions. One key and one credit pool across the whole catalog, so adding a source costs nothing up front.

Planning something large? Tell us the volume and the sources and we will come back with what it costs and what we would have to build.