# MercadoLibre Scraper: Products, Prices, Sellers & Deals (`hyperbach/mercadolibre-scraper`) Actor

MercadoLibre API and scraper for products and prices in Argentina, Mexico and Colombia: search, category lists, sellers, official stores, deals (ofertas) and best sellers (mas vendidos). Price, discount, sold count, rating, seller, shipping; product pages on request. No login. Misses free.

- **URL**: https://apify.com/hyperbach/mercadolibre-scraper.md
- **Developed by:** [Hyperbach](https://apify.com/hyperbach) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 product cards

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## MercadoLibre Scraper: Products, Prices, Sellers & Deals

**MercadoLibre products from Argentina, Mexico and Colombia, logged out: search words, list links, sellers' ids or official stores in; one row per product out — the item, catalog and user-product ids, the title, URL and image, the price in the site's own currency, the old price and the discount, the installments, the sold count, the rating and the review count, the seller and the official store, free shipping and FULL, the international flag, the condition, the category, the organic position and the list it came from.** Sort and filters are MercadoLibre's own (price, condition, free shipping, FULL, official stores, discount), and each input's free row names the filters the page applied. Paste a product's link for its page's own row, or switch on `productDetails` to add each card's product page: the description, the pictures, the specs, the stock, the seller's reputation, the warranty, the buy box's offers and the first reviews. No login, no cookies, no account; proxies and MercadoLibre's bot check handled for you.

**From $2.00 per 1,000 rows (`product`) on the Free plan, $1.00 on Starter; every row and add-on is priced under Pricing below.** A run start is $0.005. The default input returns about 50 rows for about $0.105. Every input gets one free row with its verdict; a search MercadoLibre matches nothing for (`no_results`: its loose list is never delivered), a page with no product list (`not_a_list`), a product link that did not land on a product (`not_a_product`), a filter or sort the page did not apply (`filter_not_applied`: the wrong list is never delivered), and a page the run could not open on any connection it tried (`failed`) are named there and never charged.

![A Mercado Libre Mexico product page in a browser: a pair of grey sneakers with the sold count, the rating, the old price, the price, the discount, the installments, free shipping and the seller. Beside it, the row this Actor returns, with sold_count highlighted, then the title, price, old price, discount, installments text, rating, review count, shipping text and seller.](https://api.apify.com/v2/key-value-stores/dcLLNGq99686o2A4v/records/hero-mercadolibre-scraper.webp)

### How it compares

- **Cheaper than piotrv1001's MercadoLibre Scraper, with more data:** $1.10 per 1,000 products, against $2.00; 41 fields per product, against 29. It is 3 times faster: 50 products in 6.1 s, against our 18 s.
- **Faster than sourabhbgp's MercadoLibre Scraper, with more data:** 50 products in 18 s, against 32 s; 41 fields per product, against 33. The price is about the same: $1.10 per 1,000 products, against $1.10.

Measured on 2026-11-14. Each line compares one job, run by both scrapers at the same time. Prices are per 1,000 products: Apify Actors at the Scale plan's prices.

### Tested head-to-head on 2026-11-14

The job: the first 50 organic MercadoLibre Argentina cards of the search "zapatillas deportivas" (the input schema's example), one row per product card. Every Actor ran on it the same day from the same harness; every run's cost is at the Scale plan's prices: a rival's charged events at its price for that plan, this Actor's at its list price. Fields counts the filled fields of a typical row. Every row here is an organic card of the same Argentina search; sourabhbgp charges a search start and each row, piotrv1001 each row, and our rows carry the card's sold count, installments and organic position. Re-measured monthly.

| Actor | Rows | First row | Run time | Cost | Fields | Failures |
|---|---|---|---|---|---|---|
| **this Actor** | 50 | 7.7 s | 18 s | $0.055 | 41 | none |
| `sourabhbgp/mercadolibre-scraper` | 50 | 25 s | 32 s | $0.055 | 33 | none |
| `piotrv1001/mercado-libre-listings-scraper` | 50 | 4.4 s | 6.1 s | $0.10 | 29 | none |

### Why this MercadoLibre scraper

- **Three countries, one schema.** Argentina, Mexico and Colombia, each read on its own site; every row names its `site` and keeps the card's own `currency` (ARS, MXN, COP, and USD where a seller prices in dollars), never converted. The other Spanish-language sites (Chile, Peru, Uruguay and 11 more) are not read yet: each needs its own measured unblocker recipe first, and a link of one of them gets a free row that says so.
- **The filter you asked, or a free row.** Sort, price band, condition, free shipping, FULL, official stores and minimum discount are MercadoLibre's own, set in the first page's address. The page's own list of applied filters is read on page 1: a search whose page did not apply what you asked gets a free `filter_not_applied` row instead of a charged walk of the wrong list. Each input's row names the filters and the sort the page applied (`applied_filters`, `sort`). In the build's same-minute tests each filter changed the list against the unfiltered one (FULL 34 of 36 cards against 23 of 48, used 48 of 48 against 0, at least 30 % off 37 of 37 against 1 of 48).
- **Sponsored cards honest.** A search page carries sponsored cards on top of its 48 results, some of them repeats of organic ones. They are left out and not charged by default; `includeSponsored` delivers them with `sponsored` true and no organic `position`. `position` is the organic place in the whole list (1 = first), as the page orders it.
- **The list to its end.** A search is walked page by page to the source's own end (MercadoLibre lists at most 42 pages of 48 products, about 2,000, whatever its count says: TRUNCATED with the count), several pages at once; a page refused on every connection ends the input PARTIAL with the page named, never a silent short list.
- **Product pages too.** A product's link (a catalog `/p/` page, a listing `articulo.` page or a `/up/` link) gives one row from its own page, and `productDetails` reads each card's page after the cap took the card: the description, the pictures and videos, the full spec table, the stock, the seller's reputation and sales, the warranty and returns, the payment methods, the buy box's other offers and the page's first reviews (rating, text, date, country; no reviewer name). A page that could not be read leaves the card's row as the list showed it, with `details_status` saying why.
- **No silent empty run.** A word nothing matches makes MercadoLibre answer a loose list of unrelated products (58 dresses for a nonsense word in the build's tests); the run reads the titles and the search's own word stems and writes a free `no_results` row instead of charging them. Every input gets a row that says what happened.

### Who it's for

- **Sellers and brands on MercadoLibre** — Read a category's search or your competitors' lists in Argentina, Mexico or Colombia with the price, the discount, the sold count and the rating, see who is sponsored and who ranks first organically, and read a seller's or an official store's whole catalogue.
- **Price and market researchers** — Track prices, discounts and the deals for a basket of searches across Latin America, each in its site's own currency, with the filters MercadoLibre itself applies.
- **Catalog and data teams** — Pull a seller's or an official store's list, the best sellers or the deals as rows with stable item and catalog ids for a feed.

### Quick start

**Basic — newest postings**

```json
{
  "maxItems": 10
}
```

### Switching from `karamelo/mercadolibre-scraper-espanol-castellano`?

Your input works as it is. Each name in the left column is read as this Actor's own field and the run log says so (`read <theirs> as <ours>`); a name marked *not read* is ignored with a note. A value in the other Actor's shape, an object list or its own date form, is read too.

| karamelo/mercadolibre-scraper-espanol-castellano | this Actor | what to know |
|---|---|---|
| `keyword` | `searchTerms` | Read as one search of `searchTerms` (one search a line there). |
| `country` | `site` | The leader's site address (https://listado.mercadolibre.com.mx/) is read as its country code (mx); a code, a site id (MLM) or a country's name works too. Brazil is not read here. |
| `sort` | `sort` | The same three values: relevance, price_asc, price_desc. |
| `maxPages` | `maxPages` | The same: the most pages a search is read to (48 products a page); 0 or empty = to the list's own end (at most 42 pages). |
| `promoted` | `includeSponsored` | The same switch: on, the sponsored cards are rows too, each flagged `sponsored`. |
| `extractProductDetails` | `productDetails` | The same switch: on, each card's product page is read and its fields (description, pictures, specs, stock, seller's reputation, warranty, offers, first reviews) are on the card's row. |
| `maxProductDetails` | *not read* | Not read as its own cap: with productDetails every row is read with its page, so maxItems caps the product pages too. |
| `includeReviews` | *not read* | Not a switch here: the product page's first reviews come on each row with productDetails (`reviews`); `rating` and `reviews_count` come from the card. |

**What differs:**

- The leader takes one `keyword`; here `searchTerms` takes many searches, and `keyword` is read as one of them.
- The leader's `country` is the site's list address (https://listado.mercadolibre.com.ar/); here `site` takes the country code (ar, mx, co, …), and the leader's address is read as the code it names.
- The leader's columns are Spanish (`productoTitulo`, `precio`, …) and its price is text; here the columns are English (`title`, `price`, `original_price`, …) and every price is a number with its own `currency`.
- The leader's `extractProductDetails` is `productDetails` here (each card's product page on its row); there is no separate cap for it: `maxItems` caps the rows, each read with its page. The questions and answers are not offered yet.

### Output

One row per product, and one free summary row per input:

| field | meaning |
|---|---|
| `record_type` | `product` on a product row (charged); `target` on an input's free summary row. |
| `status` | `ok` (a charged product, or an input that delivered), or why a row is free: `no_results` (MercadoLibre matches nothing for the search), `not_a_list` (a page with no product list, such as the official stores' index for a store name that is not a store), `filter_not_applied` (the page did not apply a filter or the sort you asked), `not_found` (the page says it does not exist), `invalid_input` (a value that names nothing, or a product page), `failed` (the page was refused on every connection the run tried), `not_read` (the run stopped before it). |
| `input` | The value you gave that this row answers. |
| `site` | The MercadoLibre site the row was read on, by its country code (ar, mx, co, …). |
| `position` | The product's organic place in the whole list (1 = first), as the page orders it; empty on a sponsored card. On the best sellers, its rank in its category's list. |
| `page` | The list page the card was read on (48 products a page). |
| `id` | The listing's item id (MLA…, MLM…, MCO…: the site's prefix and the number). |
| `catalog_product_id` | The catalog product's id when the card is a catalog product (its page is `/p/<id>`); empty otherwise. |
| `user_product_id` | The user-product id (…U…) MercadoLibre gives a seller's product, when the card names one. |
| `url` | The product's own page (never the sponsored card's click-counter link). |
| `title` | The card's title. |
| `image` | The card's picture (the first of the product's gallery). |
| `price` | The price the card shows, a number in `currency` (the page's exact figure with its cents when the card rounds it). |
| `currency` | The card's own currency (ARS, MXN, COP, CLP, PEN, UYU, BOB, CRC, DOP, GTQ, HNL, NIO, PAB, PYG, USD, …); never converted. |
| `original_price` | The crossed-out old price, when the card shows one. |
| `discount_pct` | The page's own discount in percent ("38% OFF"). |
| `price_label` | The words the card shows beside the price (a payment method's price or a coupon), when it shows any. |
| `installments_count` | The number of installments on the card's installments line. |
| `installment_amount` | The amount of one installment. |
| `installments_no_interest` | True when the installments cost no more than the price ("Mismo precio", "sin interés"). |
| `installments_text` | The installments line as the card shows it ("Mismo precio 3 cuotas de $ 18.395"). |
| `sold_count` | The sold count the page carries for the product (a lower bound where the card shows "+10 mil vendidos"). |
| `sold_text` | The sold count as the card shows it, when it shows one. |
| `rating` | The product's average rating, 1 to 5. |
| `reviews_count` | The number of ratings the page counts for the product, when the page names it. |
| `seller_name` | The seller: the card's seller line, the seller behind a brand's official store ("WILSON por AJAXGOLD" → AJAXGOLD), or the seller whose list you read. |
| `seller_id` | The seller's numeric id, on a seller's list (sellerIds or a `_CustId_` link). |
| `official_store` | True when the product is sold by an official store. |
| `official_store_name` | The official store's name the card shows ("TOPPER", or the brand of "WILSON por AJAXGOLD"). |
| `brand` | The brand the page's own product list names, when it names one. |
| `free_shipping` | True when the card offers free shipping. |
| `full_shipping` | True when the product ships by MercadoLibre's FULL fulfilment. |
| `logistic_type` | The shipping logistics the page names (full, cross_docking, self_service, …). |
| `shipping_text` | The shipping line as the card shows it ("Llega gratis hoy", "Envío gratis"). |
| `international` | True on an international purchase (the card's "Internacional" line). |
| `international_text` | Where an international purchase ships from, as the card says ("China"). |
| `condition` | The condition: `used`, `refurbished` or `open_box` where the card names one, the condition filter's value when the page applied it, else empty (a card names only a condition that is not new). |
| `category_id` | The product's category id (MLA109027, …). |
| `category_path` | The category ids from the top category down to the product's own. |
| `domain_id` | MercadoLibre's product domain (MLA-SNEAKERS, …). |
| `highlight` | The card's highlight label ("MÁS VENDIDO", "OFERTA DEL DÍA", "¡ÚLTIMA!"). |
| `promotions` | The card's promotion lines (a coupon, a bank promotion), when it shows any. |
| `variations_text` | The card's line about the product's variations ("Disponible en 5 colores"). |
| `other_offer_text` | The card's other buying option, as the card says ("Otra opción de compra"). |
| `other_offer_type` | The other option's kind, as its link names it (BEST_PRICE, …). |
| `other_offer_price` | The other option's price. |
| `other_offer_url` | The other option's page. |
| `sponsored` | True on a sponsored card (delivered only with `includeSponsored`). |
| `also_sponsored` | True when the page also shows this organic product as a sponsored card. |
| `list_name` | On the best sellers: the category list the product ranks in ("Más vendidos en Celulares"). |
| `list_url` | The list page the row was read from. |
| `query` | The search words the page says it searched. |
| `count_text` | The list's result count as the page shows it ("5.932 resultados", "+9.999 resultados"). |
| `total_results` | On an input's row: the list's result count as a number. |
| `applied_filters` | On an input's row: the filters the page says it applied (each with its id, name and value). |
| `sort` | On an input's row: the sort the page says it applied (relevance, price_asc, price_desc). |
| `related_searches` | On an input's row: the related searches the page suggests. |
| `details_status` | Whether the row's product page was read: `served` (its fields are on the row: a product link's row, or a card with **Product details** on), `refused` (the page could not be opened; the card's own fields stay), `not_found`, `not_a_product`, `cut` (the run's time limit came first); empty when not asked. |
| `page_format` | The product page's kind: `catalog` (a catalog product, /p/), `user_product` (a /up/ page) or `listing` (a seller's own listing). |
| `subtitle` | The page's line above the title ("Nuevo | +10 mil vendidos"). |
| `description` | The seller's description, as the page shows it. |
| `pictures` | The product's pictures, in the page's order. |
| `videos` | The product's short videos, when the page has any. |
| `specs` | The page's spec table, each `{name, value, group}` (the full technical table where the page has one). |
| `variations` | The product's variation pickers, each `{name, selected, options, option_ids, option_urls}` (color, size, …; each option's own id and its link where the page gives one). |
| `available_quantity` | The stock the page counts. |
| `stock_text` | The page's stock line ("Último disponible", "+50 disponibles"). |
| `listing_type` | The listing's type (gold_special, gold_pro, …). |
| `card_price` | The total in installments where the page shows one. |
| `price_without_taxes` | Argentina's product pages: the price without national taxes the page shows ("Precio sin impuestos nacionales"). |
| `seller_reputation` | The seller's reputation level (5_green, …). |
| `seller_level` | The seller's MercadoLíder level (platinum, gold, silver), when it has one. |
| `seller_status` | The seller's status line on the page ("MercadoLíder Platinum"). |
| `seller_sales_text` | The seller's sales count as the page shows it ("+10 mil"). |
| `official_store_id` | The official store's id, when the seller is one. |
| `local_pickup` | True when the page offers pickup. |
| `import_taxes_text` | The import taxes line of an international product. |
| `coupon_text` | The page's coupon line, when it shows one. |
| `highlight_rank_text` | The highlight's rank line ("1º en Zapatillas"). |
| `warranty` | The warranty line. |
| `returns_text` | The returns line ("Devolución gratis"). |
| `return_days` | The days to return the product, from the page's own return policy. |
| `free_return` | True when the return is free. |
| `payment_methods` | The payment methods the page lists, each `{group, options}`. |
| `buy_box_offers` | A catalog product's offers in the buy box, each `{item_id, type, label, price, original_price, seller, selected}`. |
| `reviews` | The first reviews the product page shows, each `{rating, text, date_text, created, likes, country}`; no reviewer name. |
| `reviews_with_text` | The reviews with a written comment, as the page counts them. |
| `verdict` | On an input's row: COMPLETE (read to the list's end), LIST_END (the list's last page was read and its rows fall short of the count it shows: `note` says by how many), TRUNCATED (the source lists fewer pages than its count), CAPPED (maxPages, or the input's share of maxItems), PARTIAL (stopped early: `note` says why). |
| `rows_delivered` | On an input's row: the product rows it delivered. |
| `note` | Why an input's row has the status or the verdict it has. |
| `scraped_at` | When this row was read (UTC). |

Example record:

```json
{
  "record_type": "product",
  "status": "ok",
  "input": "https://www.mercadolibre.com.mx/mas-vendidos",
  "site": "mx",
  "position": 1,
  "page": 1,
  "id": "MLM2851918343",
  "catalog_product_id": "MLM44007277",
  "user_product_id": "MLMU3896765754",
  "url": "https://www.mercadolibre.com.mx/audifonos-in-ear-bluetooth-para-celulares-tablets-y-laptops-conexion-automatica-resistente-al-agua-y-polvo-ip55-comodo-de-llevar-estuche-de-carga-gran-capacidad-marca-mvpsmart-r30-blanco/p/MLM44007277",
  "title": "Audífonos In-ear Bluetooth Para Celulares, Tablets y Laptops, Conexión Automática, Resistente al Agua y Polvo IP55, Cómodo de Llevar, Estuche de Carga Gran Capacidad, Marca MVPSMART R30 Blanco",
  "image": "https://http2.mlstatic.com/D_NQ_NP_851731-MLA100096823243_122025-O.webp",
  "price": 124,
  "currency": "MXN",
  "original_price": 218,
  "discount_pct": null,
  "price_label": null,
  "installments_count": null,
  "installment_amount": null,
  "installments_no_interest": null,
  "installments_text": null,
  "sold_count": null,
  "sold_text": null,
  "rating": null,
  "reviews_count": null,
  "seller_name": null,
  "seller_id": null,
  "official_store": null,
  "official_store_name": null,
  "brand": null,
  "free_shipping": true,
  "full_shipping": null,
  "logistic_type": null,
  "shipping_text": "Envío gratis",
  "international": null,
  "international_text": null,
  "condition": null,
  "category_id": "MLM1144",
  "category_path": null,
  "domain_id": null,
  "highlight": null,
  "promotions": [
    "$ 100 OFF con Cupón"
  ],
  "variations_text": null,
  "other_offer_text": null,
  "other_offer_type": null,
  "other_offer_price": null,
  "other_offer_url": null,
  "sponsored": false,
  "also_sponsored": null,
  "list_name": "Más vendidos en Consolas y Videojuegos",
  "list_url": "https://www.mercadolibre.com.mx/mas-vendidos",
  "query": null,
  "count_text": null,
  "total_results": null,
  "applied_filters": null,
  "sort": null,
  "related_searches": null,
  "details_status": "refused",
  "page_format": null,
  "subtitle": null,
  "description": null,
  "pictures": null,
  "videos": null,
  "specs": null,
  "variations": null,
  "available_quantity": null,
  "stock_text": null,
  "listing_type": null,
  "card_price": null,
  "price_without_taxes": null,
  "seller_reputation": null,
  "seller_level": null,
  "seller_status": null,
  "seller_sales_text": null,
  "official_store_id": null,
  "local_pickup": null,
  "import_taxes_text": null,
  "coupon_text": null,
  "highlight_rank_text": null,
  "warranty": null,
  "returns_text": null,
  "return_days": null,
  "free_return": null,
  "payment_methods": null,
  "buy_box_offers": null,
  "reviews": null,
  "reviews_with_text": null,
  "verdict": null,
  "rows_delivered": null,
  "note": null,
  "scraped_at": "2026-11-13T18:37:38Z"
}
```

### Pricing

**Pay for the rows a run delivers**, plus one run start; no platform usage and no proxy is billed to you. The row prices fall with your Apify plan.

| event | unit | Free | Starter | Scale | Business |
|---|---|---|---|---|---|
| Product card (`product`) | per 1,000 | $2.00 | $1.00 | $1.00 | $1.00 |
| Product with its page (`product_page`) | per 1,000 | $4.00 | $2.50 | $2.00 | $2.00 |
| Run start (`start`) | per run | $0.005 | $0.005 | $0.005 | $0.005 |

A product card is **$2.00 per 1,000** on the Free plan ($0.002 a row) and $1.00 on Starter. A row read from the product's own page (a product link, or a card with `productDetails` on) is **$4.00 per 1,000** on the Free plan ($0.004 a row) and $2.50 on Starter, in place of the card's charge; a card whose page could not be read is charged as a card. Each run that delivers a charged row also pays the **run start, $0.005 once**; a run that delivers none pays nothing at all. So 50 cards cost $0.105 on the Free plan and $0.055 on Starter; 1,000 cards cost $2.005 and $1.005; 50 cards with their pages cost $0.205 on the Free plan and $0.13 on Starter; every input of a run shares one start. Never charged: every input's own row (its verdict, the list's count and the filters the page applied), a search MercadoLibre matches nothing for, a page with no product list, a product link that did not land on a product, a filter or sort the page did not apply, a page refused on every connection tried, a sponsored card left out, a product another input of the run already delivered, a card under your `minDiscount`, and an input left unread at `maxItems`, your charge limit or the time limit. A run that stops early (a timeout, an abort) is charged for the rows it delivered.

Before the first request the log names the prices at your plan and the most the run can cost: `maxItems` over the whole run (shared evenly by the inputs), at most 42 pages of a list (about 2,000 cards), one row a product link, and never more than your charge limit. Enterprise plans have their own rates: the Actor's Pricing tab shows the price for your plan.

### Usage patterns

- **Search by words** — Put `zapatillas deportivas` (one search a line) in **Search words**, pick the **Country (MercadoLibre site)** and set **Max results (whole run)** (shared evenly by the searches). Each row is one product card with its price, old price, installments, sold count, rating, seller and shipping; the search's own row says COMPLETE, LIST_END (the last page read short of the count it shows), TRUNCATED (the source lists at most 42 pages), CAPPED or PARTIAL. **Sort** and the filters (price band, condition, free shipping, FULL, official stores, minimum discount) are MercadoLibre's own, set before the first page; the search's row names the filters the page said it applied.
- **Read a list, a seller, an official store, the deals or the best sellers** — Paste the link from your browser in **MercadoLibre list links**: a search or category list `https://listado.mercadolibre.com.mx/...` (read with its own filters and sort), a seller's `https://listado.mercadolibre.com.ar/_CustId_<seller id>`, an official store's `https://www.mercadolibre.com.co/tienda/<store>`, the deals `https://www.mercadolibre.com.ar/ofertas`, the best sellers `https://www.mercadolibre.com.mx/mas-vendidos` (one ranked list per category, each row with its list's name and rank), or one category's best sellers `https://www.mercadolibre.com.ar/mas-vendidos/MLA1055`. A link the site has moved (a renamed category, a store's old link) is read at the site's own new path when that path keeps every filter the link asks; otherwise its row says where the site sent it. A link is read on its own site. Or give sellers' ids in **Sellers' ids** and stores' names in **Official stores**: they are read on the site you pick, with your sort and filters.
- **Read products by their links, or each card's product page** — Paste product links in **MercadoLibre list links** (`https://www.mercadolibre.com.ar/<name>/p/MLA…`, `https://articulo.mercadolibre.com.mx/MLM-…-_JM`): each gives one row from its page with the description, the pictures, the specs, the stock, the seller's reputation, the warranty, the buy box's offers and the first reviews. Or switch on **Product details** with a search or a list: each card's own page is read and its fields are added to the card's row (`details_status` served), at the product-page price.

### Input configuration

| field | type | default | what it does |
|---|---|---|---|
| `searchTerms` | `array` | `[]` | Words as you would type them in MercadoLibre's search box, one search per line (for example zapatillas deportivas). Each search is read on the site you pick below, page by page, to the end of the list or your limits. |
| `startUrls` | `array` | `[]` | Links copied from MercadoLibre Argentina, Mexico or Colombia: a search or category list (listado.mercadolibre.com.ar/...), a filtered or sorted list, a seller's list (...*CustId*<id>), an official store (/tienda/<name>), the deals (/ofertas), the best sellers (/mas-vendidos, or a category's /mas-vendidos/MLA1055), or a product (www.mercadolibre.com.ar/<name>/p/MLA..., articulo.mercadolibre.com.mx/MLM-...-\_JM): a product's link gives one row from its own page. Each link is read on its own site. |
| `sellerIds` | `array` | `[]` | Sellers' numeric ids (the digits after *CustId* in a seller's list link): every product the seller lists on the site you pick. |
| `officialStores` | `array` | `[]` | Official stores by the name in their link (for example topper for mercadolibre.com.ar/tienda/topper): every product the store lists on the site you pick. |
| `site` | `ar` / `mx` / `co` | `"ar"` | The MercadoLibre site the search words, sellers and stores are read on: Argentina, Mexico or Colombia. Links are always read on their own site. The other Spanish-language sites are not read yet. |
| `sort` | `relevance` / `price_asc` / `price_desc` | `"relevance"` | The order MercadoLibre lists the products in (searches, sellers and stores). |
| `minPrice` | `integer` |  | Only products from this price, in the site's own currency. Empty or 0 = no minimum. |
| `maxPrice` | `integer` |  | Only products up to this price, in the site's own currency. Empty or 0 = no maximum. |
| `condition` | `any` / `new` / `used` / `refurbished` / `open_box` | `"any"` | Only new, used, refurbished or open-box products, as MercadoLibre's own condition filter applies it. |
| `freeShipping` | `boolean` | `false` | Only products with free shipping. |
| `fullShipping` | `boolean` | `false` | Only products shipped by MercadoLibre's FULL fulfilment. |
| `officialStoresOnly` | `boolean` | `false` | Only products sold by official stores. |
| `minDiscount` | `integer` | `0` | Only products discounted at least this much. The list is asked at MercadoLibre's own step at or under it (5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80; under 5 the step 5), and a product under your minimum is left out, free. 0 = any. |
| `includeSponsored` | `boolean` | `false` | Sponsored cards (ads) are left out by default. On: they come too, each with sponsored true and no position. |
| `productDetails` | `boolean` | `false` | Off by default. On: each card's own product page is read too, and its fields are added to the card's row: the description, the pictures, the specs, the stock, the seller's reputation, the warranty, the buy box's offers and the first reviews (details_status served). Charged at the product-page price instead of the card's; a page that cannot be read leaves the card's row as the list showed it, at the card's price. |
| `maxItems` | `integer` | `0` | The most product rows of the whole run, shared evenly by its searches, links, sellers and stores (an input whose list ends short leaves the rest of its share to the others); 0 = no cap beyond your charge limit. |
| `maxPages` | `integer` | `0` | The most pages read of each search or list (48 products a page; MercadoLibre lists at most 42 pages of a list). 0 = to the end of the list. |
| `feedback` | `string` |  | A note to the people who maintain this Actor: what you needed and did not get. For example a missing field, a wrong or empty result, or the Actor you switch from or to, and why. The run does not read it: the rows and the charges stay the same. A person reads every note. |

### Errors

**A run does not fail because of your input.** When an input cannot be used — a date that is not a date, an id in the wrong form, two settings that contradict each other — the run ends **Succeeded**, charges nothing, and says what to change:

- the status message starts with `INPUT REJECTED`;
- the dataset holds one row, `{"error": true, "code": "…", "message": "…"}`, and no results;
- the key-value store record `ERROR` holds the same object.

From code, check `error` on the first row before reading results.

A value that names nothing (an empty line, a link of another site, Brazil's mercadolivre.com.br, a product's id without its link, an index page) is not an error: it gets one free row with `status` invalid_input that says why, and the run goes on with the others. A run that ends **Failed** is a fault on our side, never your input; it charges nothing, and we are alerted.

### FAQ

**Which countries?**

Argentina (ar), Mexico (mx) and Colombia (co). The other 14 Spanish-language MercadoLibre sites (Bolivia, Chile, Costa Rica, the Dominican Republic, Ecuador, Guatemala, Honduras, Nicaragua, Panama, Paraguay, Peru, El Salvador, Uruguay, Venezuela) are not read yet: MercadoLibre walls a logged-out reader, each site is read through an unblocker recipe measured for it, and those recipes come later. Brazil (mercadolivre.com.br) is read by hyperbach/mercadolivre-scraper.

**Which price is which?**

`price` is the price the card shows, in the card's own `currency` (a seller can price in USD on a site whose currency is another). `original_price` is the crossed-out old price and `discount_pct` the page's own discount; `installments_count`, `installment_amount` and `installments_no_interest` read the installments line ("Mismo precio 3 cuotas de $ 18.395").

**Why does a search stop near 2,000 products when it counts more?**

MercadoLibre lists at most 42 pages of 48 products for any search or list, whatever its count text says ("+9.999 resultados"). The search's row says TRUNCATED with the count; narrow it with filters, a price band or more words to read the rest.

**Can I get the description, the specs, the gallery, the stock or the Q\&A?**

The description, the pictures, the specs, the stock and the seller's details: yes, from each product's own page — paste the product's link, or switch on **Product details** for a search's or a list's cards. The questions and answers are not offered yet. Without Product details, the card's own fields (title, price, old price, discount, installments, sold count, rating, review count, seller, official store, shipping, condition, category, international flag) are on every row.

**What is a free row?**

Every input gets one row with `record_type` target that says what it gave: its verdict, the rows it delivered, the list's count and the filters the page applied, or why it gave none (`no_results`, `not_a_list`, `filter_not_applied`, `not_a_product`, `invalid_input`, `failed`, `not_read`). Those rows are never charged.

**Do I need Apify Proxy or my own proxy?**

No. The Actor uses its own connections, at no extra cost to you.

### Integration

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });
const run = await client.actor('hyperbach/mercadolibre-scraper').call({"maxItems": 10});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')
run = client.actor('hyperbach/mercadolibre-scraper').call(run_input={'maxItems': 10})
items = client.dataset(run['defaultDatasetId']).list_items().items
```

#### CLI

```bash
apify call hyperbach/mercadolibre-scraper --input '{"maxItems": 10}'
```

#### REST

```bash
curl -X POST "https://api.apify.com/v2/acts/hyperbach~mercadolibre-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H 'Content-Type: application/json' -d '{"maxItems": 10}'
```

#### AI agents and MCP

Apify's MCP server offers this Actor as a tool to Claude, Cursor, VS Code and any other MCP client. Connect `https://mcp.apify.com?tools=hyperbach/mercadolibre-scraper` and ask, for example: "Get 100 products from MercadoLibre Argentina for zapatillas deportivas with the price, the old price, the seller, the sold count and free shipping". The agent fills the input from the table above and reads the rows from the run's dataset. A field under the name another Actor gives it is read as this Actor's own: `keyword`, `keywords`, `search`, `searches` as `searchTerms`; `urls`, `url`, `links`, `listUrls` as `startUrls`; `sellerId`, `seller`, `sellers`, `sellerID` as `sellerIds`; `officialStore`, `store`, `stores`, `storeSlugs` as `officialStores` (and more). An agent or a person can add `feedback` to any run and say what was needed and not delivered: a missing field, a wrong or empty result, the Actor switched from or to, and why. The run returns the same rows at the same price, and a person reads every note.

#### n8n, Make and Zapier

The Apify node in n8n, the Apify app in Make and the Apify integration in Zapier run this Actor on a schedule or from a trigger and read its dataset. A webhook on the run's end (Integrations on the Actor page) sends the rows on to your own endpoint. Nothing to install on our side.

### Support

**Disagree with a charge?** Write to apify@hyperbach.com with the run ID. We will ask Apify to compensate you, and the charge comes back to your Apify account as platform credit.

**Did it do the job?** A short [review on the Store](https://apify.com/hyperbach/mercadolibre-scraper/reviews), at any rating, helps the next buyer choose.

### See also

- **[Amazon Product Details Scraper](https://apify.com/hyperbach/amazon-product-details-scraper)** — Amazon products by ASIN, URL or UPC / EAN / ISBN on 21 Amazon stores: the buy-box price, every best-seller rank, the rating and the review summary.
- **[AliExpress Product Details Scraper](https://apify.com/hyperbach/aliexpress-product-details-scraper)** — AliExpress products by URL or item id: every SKU with its own price and stock, in the country and currency you choose.
- **[Shopify Store Scraper](https://apify.com/hyperbach/shopify-products-scraper)** — every product of a Shopify store, with its variants, prices and images.
- **[Alibaba Products Scraper](https://apify.com/hyperbach/alibaba-scraper)** — the products of an Alibaba.com search: price range, minimum order and the supplier with its country and verification.
- **[Walmart Products Scraper](https://apify.com/hyperbach/walmart-scraper)** — Walmart products by search, category or URL: the price with the was-price, the seller and the rating.
- **[Coles Scraper](https://apify.com/hyperbach/coles-scraper)** — Coles Australia products and specials, with the price, the was-price and the unit price.

*This page is generated from the Actor's schemas and a live sample — it cannot describe a field the Actor does not have.*

# Actor input Schema

## `searchTerms` (type: `array`):

Words as you would type them in MercadoLibre's search box, one search per line (for example zapatillas deportivas). Each search is read on the site you pick below, page by page, to the end of the list or your limits.

## `startUrls` (type: `array`):

Links copied from MercadoLibre Argentina, Mexico or Colombia: a search or category list (listado.mercadolibre.com.ar/...), a filtered or sorted list, a seller's list (...*CustId*<id>), an official store (/tienda/<name>), the deals (/ofertas), the best sellers (/mas-vendidos, or a category's /mas-vendidos/MLA1055), or a product (www.mercadolibre.com.ar/<name>/p/MLA..., articulo.mercadolibre.com.mx/MLM-...-\_JM): a product's link gives one row from its own page. Each link is read on its own site.

## `sellerIds` (type: `array`):

Sellers' numeric ids (the digits after *CustId* in a seller's list link): every product the seller lists on the site you pick.

## `officialStores` (type: `array`):

Official stores by the name in their link (for example topper for mercadolibre.com.ar/tienda/topper): every product the store lists on the site you pick.

## `site` (type: `string`):

The MercadoLibre site the search words, sellers and stores are read on: Argentina, Mexico or Colombia. Links are always read on their own site. The other Spanish-language sites are not read yet.

## `sort` (type: `string`):

The order MercadoLibre lists the products in (searches, sellers and stores).

## `minPrice` (type: `integer`):

Only products from this price, in the site's own currency. Empty or 0 = no minimum.

## `maxPrice` (type: `integer`):

Only products up to this price, in the site's own currency. Empty or 0 = no maximum.

## `condition` (type: `string`):

Only new, used, refurbished or open-box products, as MercadoLibre's own condition filter applies it.

## `freeShipping` (type: `boolean`):

Only products with free shipping.

## `fullShipping` (type: `boolean`):

Only products shipped by MercadoLibre's FULL fulfilment.

## `officialStoresOnly` (type: `boolean`):

Only products sold by official stores.

## `minDiscount` (type: `integer`):

Only products discounted at least this much. The list is asked at MercadoLibre's own step at or under it (5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80; under 5 the step 5), and a product under your minimum is left out, free. 0 = any.

## `includeSponsored` (type: `boolean`):

Sponsored cards (ads) are left out by default. On: they come too, each with sponsored true and no position.

## `productDetails` (type: `boolean`):

Off by default. On: each card's own product page is read too, and its fields are added to the card's row: the description, the pictures, the specs, the stock, the seller's reputation, the warranty, the buy box's offers and the first reviews (details_status served). Charged at the product-page price instead of the card's; a page that cannot be read leaves the card's row as the list showed it, at the card's price.

## `maxItems` (type: `integer`):

The most product rows of the whole run, shared evenly by its searches, links, sellers and stores (an input whose list ends short leaves the rest of its share to the others); 0 = no cap beyond your charge limit.

## `maxPages` (type: `integer`):

The most pages read of each search or list (48 products a page; MercadoLibre lists at most 42 pages of a list). 0 = to the end of the list.

## `feedback` (type: `string`):

A note to the people who maintain this Actor: what you needed and did not get. For example a missing field, a wrong or empty result, or the Actor you switch from or to, and why. The run does not read it: the rows and the charges stay the same. A person reads every note.

## Actor input object example

```json
{
  "searchTerms": [
    "zapatillas deportivas"
  ],
  "startUrls": [],
  "sellerIds": [],
  "officialStores": [],
  "site": "ar",
  "sort": "relevance",
  "condition": "any",
  "freeShipping": false,
  "fullShipping": false,
  "officialStoresOnly": false,
  "minDiscount": 0,
  "includeSponsored": false,
  "productDetails": false,
  "maxItems": 50,
  "maxPages": 0
}
```

# Actor output Schema

## `results` (type: `string`):

All scraped records in the default dataset. One row per product, and one free summary row per input:

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [
        "zapatillas deportivas"
    ],
    "maxItems": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("hyperbach/mercadolibre-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchTerms": ["zapatillas deportivas"],
    "maxItems": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("hyperbach/mercadolibre-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchTerms": [
    "zapatillas deportivas"
  ],
  "maxItems": 50
}' |
apify call hyperbach/mercadolibre-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hyperbach/mercadolibre-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/3wBWkxk16OMnpC3IW/builds/31xmyD8nAqyOaz52z/openapi.json
