{
  "openapi": "3.0.1",
  "info": {
    "title": "Otomoto.pl Scraper By Mileage, Fuel & Gearbox",
    "description": "Otomoto.pl Scraper by Mileage, Fuel & Gearbox extracts vehicle listings from Otomoto.pl using mileage, fuel type, and gearbox filters. Collect prices, specs, seller details, locations, and car data for market research, price tracking, competitor analysis, and lead generation.",
    "version": "0.1",
    "x-build-id": "oSFJKk0BJH9qGd4n9"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapier~otomoto-pl-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapier-otomoto-pl-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/scrapier~otomoto-pl-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapier-otomoto-pl-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/scrapier~otomoto-pl-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapier-otomoto-pl-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "startUrls": {
            "title": "🔗 Paste Otomoto URLs (skips every filter below)",
            "type": "array",
            "description": "Full Otomoto.pl URLs - listing pages (https://www.otomoto.pl/osobowe/bmw) or single adverts (https://www.otomoto.pl/osobowe/oferta/volvo-xc-40-ID6IbdLC.html). ⚠️ When this list is non-empty it OVERRIDES every search and vehicle-spec filter below, because your URL already carries the filters you built in the browser; the run log names each filter it had to ignore. A sold or removed advert produces a free, uncharged row with the reason instead of vanishing.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "category": {
            "title": "🏷️ Otomoto section",
            "enum": [
              "cars",
              "vans",
              "trucks",
              "motorcycles",
              "trailers",
              "campers",
              "construction",
              "agricultural",
              "parts"
            ],
            "type": "string",
            "description": "Which part of Otomoto to search. The vehicle-spec vocabularies below were measured on the CAR section (osobowe); motorcycles, trucks and machinery carry different parameter sets. Otomoto has moved several sections and the actor follows them: motorcycles → /motocykle-i-quady, trailers → /przyczepy, construction → /maszyny-budowlane, agricultural → /maszyny-rolnicze, and the standalone campers section was retired so campers are searched as the camper body type inside /dostawcze.",
            "default": "cars"
          },
          "query": {
            "title": "🚗 Make, or make + model",
            "type": "string",
            "description": "One brand, or a brand plus a model separated by a space. Examples: \"bmw\" → /osobowe/bmw · \"bmw seria 3\" → /osobowe/bmw/seria-3 · \"mercedes-benz c-klasa\". Use Otomoto's own Polish model name. Otomoto answers an unknown brand or model with HTTP 200 and the WHOLE catalogue, so the run fails instead and names the word it rejected.",
            "default": ""
          },
          "location": {
            "title": "📍 Town or voivodeship",
            "type": "string",
            "description": "A Polish town (\"Warszawa\", \"Kraków\", \"Łódź\") or a voivodeship (\"Małopolskie\", \"Mazowieckie\"). Polish characters are handled. Otomoto applies its own catchment radius around a town, so nearby localities are included; a voivodeship is an exact administrative match. An unresolvable name fails the run instead of quietly returning national results.",
            "default": ""
          },
          "sort": {
            "title": "↕️ Result order",
            "enum": [
              "relevance_web",
              "created_at:desc",
              "created_at:asc",
              "price:asc",
              "price:desc",
              "year:desc",
              "year:asc",
              "filter_float_price:asc",
              "filter_float_price:desc",
              "filter_float_mileage:asc",
              "created_at_first:desc"
            ],
            "type": "string",
            "description": "🛣️ \"Mileage: low → high\" is the order this actor exists for - it is a real Otomoto server-side key. Several other values are handled for you because Otomoto silently ignores keys it does not know: the two Price orders are remapped to Otomoto's working price keys, and the Year orders plus \"Oldest first\" are applied CLIENT-SIDE over the rows this run collected. The log always states which one ran.",
            "default": "relevance_web"
          },
          "maxItems": {
            "title": "🔢 How many adverts to scrape",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Hard cap on charged advert rows. Free accounting rows for removed adverts are never charged. Narrow spec filters legitimately return fewer rows than this - diesel + manual + estate + under 120,000 km is a genuinely small slice of the Polish market, and a short result set is not a failure. Default is 10.",
            "default": 10
          },
          "minPrice": {
            "title": "💰 Price from (PLN)",
            "minimum": 0,
            "type": "integer",
            "description": "Minimum advert price in Polish złoty. Sent as search[filter_float_price:from]."
          },
          "maxPrice": {
            "title": "💸 Price to (PLN)",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum advert price in Polish złoty. Sent as search[filter_float_price:to]."
          },
          "minProductionYear": {
            "title": "📅 Built from (year)",
            "minimum": 1900,
            "maximum": 2030,
            "type": "integer",
            "description": "Earliest production year, e.g. 2019. Sent as search[filter_float_year:from]."
          },
          "maxProductionYear": {
            "title": "📆 Built to (year)",
            "minimum": 1900,
            "maximum": 2030,
            "type": "integer",
            "description": "Latest production year, e.g. 2025. Sent as search[filter_float_year:to]."
          },
          "minMileage": {
            "title": "🛣️ Odometer from (km)",
            "minimum": 0,
            "type": "integer",
            "description": "Lowest odometer reading to accept. Most useful in reverse - set it to filter OUT suspiciously low-kilometre cars in an age bracket where they should not exist. Sent as search[filter_float_mileage:from]. Measured on /osobowe/bmw: from=200,000 narrows 19,594 adverts to 6,588."
          },
          "maxMileage": {
            "title": "🛣️ Odometer to (km)",
            "minimum": 0,
            "type": "integer",
            "description": "Highest odometer reading to accept - the filter the base scraper is missing most, because in the used trade the kilometres decide the price band, the warranty exposure and whether a car is worth transporting at all. Sent as search[filter_float_mileage:to]. Measured on /osobowe/bmw: to=50,000 narrows 19,594 adverts to 4,745. Note the odometer is what the SELLER typed; Otomoto does not verify it."
          },
          "fuelType": {
            "title": "⛽ Fuel (multi-select, union)",
            "type": "array",
            "description": "Keep only vehicles running on the fuels you pick; several picks return the union. These are Otomoto's own nine value ids for the car section - petrol+LPG matters specifically in Poland, where conversions are a normal used-car category. ⚠️ Type one value per list entry. A comma-joined entry like \"diesel,electric\" makes Otomoto answer HTTP 200 with zero adverts and no error, so the actor rejects it loudly instead.",
            "items": {
              "type": "string",
              "enum": [
                "petrol",
                "diesel",
                "petrol-lpg",
                "petrol-cng",
                "hybrid",
                "plugin-hybrid",
                "electric",
                "etanol",
                "hidrogen"
              ],
              "enumTitles": [
                "⛽ Petrol (Benzyna)",
                "🛢️ Diesel",
                "🫧 Petrol + LPG",
                "💨 Petrol + CNG",
                "🔋 Hybrid",
                "🔌 Plug-in hybrid",
                "⚡ Electric",
                "🌽 Ethanol (etanol)",
                "💧 Hydrogen (hidrogen)"
              ]
            },
            "default": []
          },
          "transmission": {
            "title": "⚙️ Gearbox (multi-select, union)",
            "type": "array",
            "description": "Manual or automatic. Otomoto's gearbox filter publishes exactly these two values - there is no \"semi-automatic\" on Otomoto, so it is not offered here rather than being offered and silently returning nothing. Measured on /osobowe/bmw: manual 4,176, automatic 15,417 of 19,594. Sent as search[filter_enum_gearbox].",
            "items": {
              "type": "string",
              "enum": [
                "manual",
                "automatic"
              ],
              "enumTitles": [
                "🕹️ Manual (Manualna)",
                "🎛️ Automatic (Automatyczna)"
              ]
            },
            "default": []
          },
          "minEnginePower": {
            "title": "🐎 Power from (KM)",
            "minimum": 0,
            "type": "integer",
            "description": "Lowest engine power to accept, in KM (koni mechanicznych, Polish metric horsepower) - the unit Otomoto itself prints and filters on. No kW conversion happens anywhere, in either direction. Sent as search[filter_float_engine_power:from]. Measured on /osobowe/bmw: from=300 narrows 19,594 adverts to 4,090."
          },
          "maxEnginePower": {
            "title": "🐎 Power to (KM)",
            "minimum": 0,
            "type": "integer",
            "description": "Highest engine power to accept, in KM. The practical use is insurance: young-driver and fleet policies price sharply above certain thresholds, so a sourcing run for that market needs a hard ceiling. Sent as search[filter_float_engine_power:to]. Measured on /osobowe/bmw: to=100 leaves 52 adverts."
          },
          "bodyType": {
            "title": "🚘 Body shape (multi-select, union)",
            "type": "array",
            "description": "Keep only the body shapes you can sell; several picks return the union. These are Otomoto's own nine car-section value ids, so the names differ from the English trade words: an estate is \"combi\", a convertible is \"cabrio\" and a hatchback is \"compact\". Otomoto publishes no pickup or van body value on the car section. Measured on /osobowe/bmw: combi 3,919 of 19,594.",
            "items": {
              "type": "string",
              "enum": [
                "sedan",
                "combi",
                "compact",
                "suv",
                "coupe",
                "cabrio",
                "minivan",
                "city-car",
                "mini"
              ],
              "enumTitles": [
                "🚗 Sedan",
                "🚙 Estate / wagon (combi)",
                "🚘 Hatchback (compact)",
                "🚜 SUV",
                "🏎️ Coupe",
                "🌤️ Convertible (cabrio)",
                "🚐 Minivan",
                "🅿️ City car",
                "🤏 Mini"
              ]
            },
            "default": []
          },
          "minEngineCapacity": {
            "title": "🔧 Capacity from (cm³)",
            "minimum": 0,
            "type": "integer",
            "description": "Smallest engine displacement to accept, in cubic centimetres. Sent as search[filter_float_engine_capacity:from]. Measured on /osobowe/bmw: 1,900-2,100 cm³ leaves 10,590 of 19,594."
          },
          "maxEngineCapacity": {
            "title": "🔧 Capacity to (cm³)",
            "minimum": 0,
            "type": "integer",
            "description": "Largest engine displacement to accept, in cubic centimetres. Sent as search[filter_float_engine_capacity:to]."
          },
          "doorCount": {
            "title": "🚪 Doors (multi-select, union)",
            "type": "array",
            "description": "Number of doors. Otomoto publishes the values 2 to 6 on the car section; 7 returns nothing anywhere and is not offered. Measured on /osobowe/bmw: 3 doors 262, 5 doors 12,947. Sent as search[filter_enum_door_count].",
            "items": {
              "type": "string",
              "enum": [
                "2",
                "3",
                "4",
                "5",
                "6"
              ],
              "enumTitles": [
                "2️⃣ 2 doors",
                "3️⃣ 3 doors",
                "4️⃣ 4 doors",
                "5️⃣ 5 doors",
                "6️⃣ 6 doors"
              ]
            },
            "default": []
          },
          "minSeats": {
            "title": "💺 Seats from",
            "minimum": 0,
            "type": "integer",
            "description": "Minimum number of seats - the way to find 7-seat family stock and minibuses. Sent as search[filter_float_nr_seats:from]. Measured on /osobowe/bmw: from=7 leaves 280 of 19,594."
          },
          "driveType": {
            "title": "🛞 Driven wheels (multi-select, union)",
            "type": "array",
            "description": "Front, rear or all-wheel drive. ⚠️ Naming trap in Otomoto's own API: the parameter behind this field is called filter_enum_transmission, but it is the DRIVE TYPE, not the gearbox - the gearbox lives in the ⚙️ Gearbox field above. Measured on /osobowe/bmw: rear-wheel 7,399, all-wheel-permanent 5,476, front-wheel 1,629.",
            "items": {
              "type": "string",
              "enum": [
                "front-wheel",
                "rear-wheel",
                "all-wheel-permanent",
                "all-wheel-auto",
                "all-wheel-lock"
              ],
              "enumTitles": [
                "🔜 Front-wheel drive",
                "🔙 Rear-wheel drive",
                "🔀 4x4 permanent (stały)",
                "🤖 4x4 automatic (dołączany)",
                "🔒 4x4 with diff lock"
              ]
            },
            "default": []
          },
          "concurrency": {
            "title": "⚡ Parallel requests",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many Otomoto pages are fetched in parallel. Default is 10, maximum 20.",
            "default": 10
          },
          "requestDelay": {
            "title": "⏱️ Pause between requests (seconds)",
            "minimum": 0,
            "maximum": 30,
            "type": "integer",
            "description": "Extra pause before each request, in seconds, plus a small random jitter. Default is 0 (no extra delay).",
            "default": 0
          },
          "proxyConfiguration": {
            "title": "Proxy settings",
            "type": "object",
            "description": "Leave disabled to run without a proxy. The actor still escalates to datacenter and then residential automatically if it is genuinely blocked.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}