{ "openapi": "3.0.1", "info": { "title": "MercadoLibre Scraper: Search, Products, Reviews, Q&A, Sellers", "description": "Scrape MercadoLibre and Mercado Livre in 18 Latin American countries. Paste a keyword or URL and get up to 2,000 search results per query, full product pages with specs and variations, product reviews, buyer Q&A, and seller catalogs. Optional product details on search rows.", "version": "0.0", "x-build-id": "D4Hb9Bf2IHy9IqjYY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sourabhbgp~mercadolibre-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sourabhbgp-mercadolibre-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/sourabhbgp~mercadolibre-scraper/runs": { "post": { "operationId": "runs-sync-sourabhbgp-mercadolibre-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/sourabhbgp~mercadolibre-scraper/run-sync": { "post": { "operationId": "run-sync-sourabhbgp-mercadolibre-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": { "mode": { "title": "Mode", "enum": [ "search", "product", "reviews", "seller" ], "type": "string", "description": "What to scrape. 'search' returns up to 2,000 organic results per keyword or search URL, in 18 countries. 'product' returns the full product page for each URL: price, brand, specs, variations, seller, warranty, top reviews and Q&A. 'reviews' returns the reviews of each product URL, one row per review. 'seller' returns a seller's catalog, one row per listing, plus a profile row for brand stores and shops.", "default": "reviews" }, "country": { "title": "Country", "enum": [ "MX", "AR", "BR", "EC", "DO", "CL", "CO", "PE", "UY", "BO", "CR", "GT", "HN", "NI", "PA", "PY", "SV", "VE" ], "type": "string", "description": "MercadoLibre country marketplace. Search mode (with or without product details), product mode and reviews mode work in all 18. MercadoLibre shows reviews in Mexico, Argentina, Brazil, Chile, Colombia, Peru, Uruguay, Ecuador and Venezuela; product pages in the Dominican Republic, Bolivia, Costa Rica, Guatemala, Honduras, Nicaragua, Panama, Paraguay and El Salvador have no reviews today, so a reviews run there ends with a 'No reviews' message and no charge. Seller mode works in every country except Costa Rica, where MercadoLibre currently shows no seller listings (the run says so and costs nothing). Pasted URLs use the country in the URL.", "default": "MX" }, "maxItems": { "title": "Max Items", "minimum": 0, "maximum": 10000, "type": "integer", "description": "How many rows to return. 0 means as many as available. Search: total results for the run, up to 2,000 per keyword or search URL. Product: product pages. Reviews: reviews per product, so 3 product URLs at 50 return up to 150 rows. Products with up to a few hundred reviews come back complete; the most reviewed products can return a couple of thousand unique reviews, because MercadoLibre limits how deep any review list can be read. Seller: total rows for the run, the profile row included, up to 2,000 listings per seller.", "default": 50 }, "searchQuery": { "title": "Search Query", "type": "string", "description": "Keyword to search, for example iphone 15. Returns up to 2,000 organic results (sponsored listings are left out). Only used in 'search' mode when no Start URLs are provided. The filters below (sort, condition, price, discount, shipping, official stores, category) apply to this keyword; they are not applied to Start URLs, which keep their own filters." }, "scrapeProductDetails": { "title": "Scrape Product Details For Each Result", "type": "boolean", "description": "Search mode: open each result's product page and add description, image gallery, seller reputation, stock, attributes, breadcrumbs, warranty, returns, shipping type, features and star breakdown to the row. Off by default; runs take longer. Paid add-on: charged on top of each Search result, and only for rows whose product page was read. See the Pricing tab.", "default": false }, "sortBy": { "title": "Sort By", "enum": [ "relevance", "price_asc", "price_desc" ], "type": "string", "description": "Search mode, with Search Query: the order MercadoLibre returns results in. Relevance is MercadoLibre's default (today's behaviour). Works in all 18 countries.", "default": "relevance" }, "condition": { "title": "Condition", "enum": [ "any", "new", "used", "refurbished" ], "type": "string", "description": "Search mode, with Search Query: only new, used or refurbished items. Any (the default) keeps all. Works in Mexico, Brazil, Argentina, Colombia, Chile, Peru, Uruguay, Ecuador and Venezuela; the other MercadoLibre sites ignore it, so a run there stops with a message and no charge.", "default": "any" }, "minPrice": { "title": "Minimum Price", "minimum": 1, "type": "integer", "description": "Search mode, with Search Query: only items priced at or above this, in the country's currency. Leave empty for no minimum. Works in Mexico, Brazil, Argentina, Colombia, Chile, Peru, Uruguay, Ecuador and Venezuela; the other MercadoLibre sites ignore it, so a run there stops with a message and no charge." }, "maxPrice": { "title": "Maximum Price", "minimum": 1, "type": "integer", "description": "Search mode, with Search Query: only items priced at or below this, in the country's currency. Leave empty for no maximum. Works in Mexico, Brazil, Argentina, Colombia, Chile, Peru, Uruguay, Ecuador and Venezuela; the other MercadoLibre sites ignore it, so a run there stops with a message and no charge." }, "minDiscount": { "title": "Minimum Discount (%)", "minimum": 1, "maximum": 99, "type": "integer", "description": "Search mode, with Search Query: only items discounted at least this much, for example 20 for 20% OFF or more. Leave empty for any. Works in Mexico, Brazil, Argentina, Colombia, Chile, Peru, Uruguay, Ecuador and Venezuela; the other MercadoLibre sites ignore it, so a run there stops with a message and no charge." }, "freeShippingOnly": { "title": "Free Shipping Only", "type": "boolean", "description": "Search mode, with Search Query: only items with free shipping. Off by default. Works in Mexico, Brazil, Argentina, Colombia, Chile, Peru, Uruguay, Ecuador and Venezuela; the other MercadoLibre sites ignore it, so a run there stops with a message and no charge.", "default": false }, "fullShippingOnly": { "title": "FULL Shipping Only", "type": "boolean", "description": "Search mode, with Search Query: only items shipped by MercadoLibre FULL (fast delivery from MercadoLibre's warehouses). Off by default. Works in Mexico, Brazil, Argentina, Colombia, Chile, Peru, Uruguay, Ecuador and Venezuela; the other MercadoLibre sites ignore it, so a run there stops with a message and no charge.", "default": false }, "officialStoresOnly": { "title": "Official Stores Only", "type": "boolean", "description": "Search mode, with Search Query: only items sold by official brand stores. Off by default. Works in Mexico, Brazil, Argentina, Colombia, Chile, Peru, Uruguay, Ecuador and Venezuela; the other MercadoLibre sites ignore it, so a run there stops with a message and no charge.", "default": false }, "categoryId": { "title": "Category ID", "pattern": "^\\s*M[A-Z]{2}\\d+\\s*$", "type": "string", "description": "Search mode: limit the search to a MercadoLibre category, by its ID, for example MLM1055 (cell phones in Mexico). Works with or without a Search Query. Leave empty for all categories. Works in Mexico, Brazil, Argentina, Colombia, Chile, Peru, Uruguay, Ecuador and Venezuela; the other MercadoLibre sites ignore it, so a run there stops with a message and no charge." }, "includeSponsored": { "title": "Include Sponsored Listings", "type": "boolean", "description": "Search mode: also return sponsored (ad) listings, marked isSponsored true. Off by default, so results are organic only, as before. Sponsored rows have no position, count toward Max Items and are charged as search results. An item shown both as an ad and organically on the same page is returned once, as its organic row.", "default": false }, "productUrls": { "title": "Product URLs", "type": "array", "description": "One or more MercadoLibre product URLs or IDs. Used by 'reviews' and 'product' modes. Accepts catalog (.../p/MLM…), listing (.../up/MLMU…) and item (articulo.*/MLM-…) URLs, and plain IDs like MLM27172669. In 'reviews' mode, an item URL returns the listing's own reviews, or, when the listing belongs to a catalog product, the same reviews its catalog URL returns. In 'product' mode, car and motorcycle ads work too. The prefilled example is a pair of Sony headphones in Mexico.", "items": { "type": "string" } }, "includeReviews": { "title": "Include Inline Reviews", "type": "boolean", "description": "In 'product' mode, include the top 5 reviews shown on the product page. For every review, use 'reviews' mode.", "default": true }, "includeQuestions": { "title": "Include Q&A", "type": "boolean", "description": "In 'product' mode, include buyer questions and seller answers from the product page, up to 20 per product.", "default": true }, "includeVariations": { "title": "Include Variations", "type": "boolean", "description": "In 'product' mode, include all product variations (color/size/storage).", "default": true }, "reviewRating": { "title": "Review Rating Filter", "enum": [ "all", "1", "2", "3", "4", "5" ], "type": "string", "description": "In 'reviews' mode, scrape only reviews with this star rating. Leave it on 'all' (the default) to sweep every rating, both sort orders and each country's own review list, which returns the most unique reviews. Picking a single rating returns that bucket only, which is a much smaller set.", "default": "all" }, "reviewOrder": { "title": "Review Sort Order", "enum": [ "relevance", "dateCreated" ], "type": "string", "description": "Sort order for reviews. 'relevance' is MercadoLibre's helpfulness-ranked default; 'dateCreated' returns newest first. With a specific rating (1-5) it sets the order of that rating's list. With 'all', both orders are already swept, so the order changes which reviews come first and, when Max Items stops the run early, which reviews you get.", "default": "relevance" }, "sellerUrls": { "title": "Seller URLs", "type": "array", "description": "One or more sellers: a seller's listings URL (https://listado.mercadolibre.com.mx/_CustId_95428411), a brand store (https://www.mercadolibre.com.mx/tienda/phone-depot, or /loja/ on Brazil), a shop page (/pagina/...), a seller profile URL (/perfil/NICKNAME), a numeric seller ID, or a plain seller nickname. A brand store returns that store's listings; the other forms return all of the seller's listings. Brand stores and shops also return one profile row.", "items": { "type": "string" } }, "includeSellerProfile": { "title": "Include Seller Profile Row", "type": "boolean", "description": "When enabled, adds one profile row per brand store or shop before its listings: followers, logo, banner, date created, tags, brand info, section menu, free trial dates and compliance flags (moderations, debts, restrictions). Sellers without a store or shop page return listings only. The profile row counts toward Max Items.", "default": true }, "maxItemsPerSeller": { "title": "Max Items Per Seller", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Per-seller cap on catalog rows. 0 = derived automatically from Max Items (divided across input sellers). Set explicitly for batch runs where you want, e.g., 100 items × 20 sellers regardless of the global cap.", "default": 0 }, "includeFeaturedItems": { "title": "Include Featured Corridor Items", "type": "boolean", "description": "No longer used: seller mode ignores this setting. Kept so saved inputs that still send it keep working.", "default": false }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Direct URLs to scrape, from any of the 18 supported marketplaces. Match the URLs to the mode: search or category URLs (or plain keywords) in search mode, product URLs in product or reviews mode, seller URLs in seller mode. The country is read from each URL. In search mode, when Start URLs are given the search keyword is not used, and if none of them can be read the run stops with a message and charges nothing.", "items": { "type": "string" } }, "maxConcurrency": { "title": "Max Concurrency", "minimum": 1, "maximum": 24, "type": "integer", "description": "How many pages are fetched at the same time. 8 is a safe default. Raise it for large reviews batches if runs feel slow. Capped at 24; search and seller mode use at most 12, product mode at most 8.", "default": 8 }, "useResidentialProxy": { "title": "Allow extra retry route for reviews", "type": "boolean", "description": "Leave this on. Product, search and seller modes always use their own retry route. In reviews mode this lets the actor retry a refused request through a different route. There is no extra charge either way: you pay only per result.", "default": true } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }