Mercado Livre Brazil Marketplace Scraper

Scrape product data from Mercado Livre Brazil (mercadolivre.com.br), Latin America's largest online marketplace. Search by keyword with the marketplace's own filters, or paste product, search, category and deals links.

Every product comes back with its price in reais, the price before discount, the discount percentage, instalment terms, shipping and free-shipping signals, the seller, stock, and the buyer rating. Turn on full details to also get the description, the complete specification table, colour and model variants with their own prices, available stock and seller reputation. Turn on opinions to get the star breakdown and the buyer opinions the marketplace publishes on the product page.

What you get

Field	Notes
itemId	The listing's own MLB code
catalogProductId	The catalogue product code, shared by every seller of the same product
title, url	Title and canonical address
brand, model	From the specification table (full details only)
categoryId, categoryPath, breadcrumb	Marketplace category and its full path
price, originalPrice, discountPercent, currency	Current price, price before discount, and the discount. Always BRL
installments, installmentsText	Number of instalments, amount each, total, and whether they are interest free
condition	new, used, refurbished or open_box (full details only)
freeShipping, fulfillment, shippingText	Free shipping, marketplace-fulfilled delivery, and the shipping promise as shown
sellerName, officialStore, seller	Seller name, official-brand-store flag, and the seller object with its id, type and reputation grade
availableQuantity, stockStatus	Units available and the stock message (full details only)
soldQuantity	Units sold, as the marketplace reports it
images, videos	Full media gallery
variants	Colour and model variants, each with its own code, address, price and availability
attributes	The full specification table, as name / value / group triples (full details only)
description	Product description (full details only)
rating, reviewCount, ratingBreakdown	Overall rating, opinion count, and the count per star level
reviews	Each opinion the marketplace publishes on the product page: rating, text, date, country, helpful votes, photos and video count
exactMatch, searchFallback	Present on a search row only when that row is a loose match: it shares none of the keyword's words with its title (see "Search fallback" below)
changeType, changedFields, firstSeenAt, lastSeenAt	Incremental mode only

Two modes

Search. Give one or more keywords. Each is searched separately and the results are merged and de-duplicated by listing id, so the same product is never returned or billed twice.

URL. Paste any mix of:

• product pages, https://www.mercadolivre.com.br/<slug>/p/MLB70040749
• bare product codes, MLB70040749
• search result pages, https://lista.mercadolivre.com.br/notebook
• deals pages, https://www.mercadolivre.com.br/ofertas
• category pages, https://www.mercadolivre.com.br/c/eletrodomesticos

Search links are walked forward page by page. Product links return one full record each.

About category and deals links. The /ofertas deals feed is where the marketplace publishes browsable product lists, 48 per page, and it is read directly. A /c/<slug> page is a marketing landing that carries no product listings at all (verified against the live page: its embedded data holds only banners and links), so a pasted category link is resolved to that category's deals feed - the landing names its category, the feed returns its products - and the run logs that this is what happened. A keyword search or a pasted lista.mercadolivre.com.br search link remains the way to walk a category's full listing set.

Search fallback: when a keyword matches loosely

The marketplace full-text matches almost any keyword, so even a nonsense query returns products - loosely related ones. Those rows are real products that the site served, and they are returned, but each row whose title shares none of the keyword's own words is marked exactMatch: false and searchFallback: true, so you can always tell a genuine match from a loose one (and a genuine search from a nonsense one) before you act on - or pay for - the row. Rows that do carry the keyword in their title are never marked.

Filters

These are the marketplace's own filters, applied at the source rather than by discarding rows afterwards, so a filtered run is genuinely cheaper and not just shorter.

• Category and brand, by the name the site shows in its own filter list. If the site does not offer that value for your keyword, the run warns and lists what it does offer, rather than silently returning an unfiltered result.
• Price range in reais, condition (new, used, refurbished, open box)
• Free shipping only, marketplace-fulfilled only
• Official brand stores only, top-rated sellers only
• Minimum discount, interest-free instalments only
• Sort by relevance, lowest price or highest price

Filters apply to keyword searches. In URL mode the link you paste already carries whatever filters you selected on the site, so these are not applied on top of it.

One honest caveat, verified live: the marketplace's own filtered pages occasionally include a couple of loose-match rows (an accessory alongside notebooks, for example) whose card carries no seller block or no instalment block. Those rows are returned with the corresponding field left unset rather than guessed, and - on keyword searches - they carry the searchFallback mark when they share none of the keyword's words with their title.

Connection: this one matters

Mercado Livre serves its search result pages and product pages only to a Brazilian consumer-grade connection. From anywhere else those two page types answer with a sign-in interstitial before any data is rendered, whatever headers or timing you use.

So the default connection for this actor is Apify Proxy, Residential tier, country Brazil, and that is what you want for the search and product data.

Everything else is cheap and needs no such connection:

• category and deals pages (/c/..., /ofertas)

If you run without a Brazilian residential connection, the actor collects those open pages and tells you plainly that the search and product pages could not be reached. It never reports a blocked run as an empty search: a run that emitted nothing because its pages were refused fails with a message naming the connection, and that holds for both kinds of page, the search and product pages that need the Brazilian connection and the category and deals pages that do not. A keyword that genuinely has no matches still succeeds with zero rows: "returned nothing" and "was refused" are two separate counters and only their conjunction is a success.

Two consequences worth knowing before you size a run:

1. A search page costs more than you would expect, because the marketplace retires a connection after it has served one such page. Measured while this actor was built: 4 of 4 result pages taken on a fresh connection came back in full (about 3 MB, 48 products each), and 12 of 12 taken on a connection that had already served one came back as a 70 KB verification page with no products, whether they were asked for by navigating, by opening a new tab, by requesting from inside the page, after clearing cookies, after a human-paced pause, scroll and click, or by replaying the session over a plain HTTP client. So the actor gives every search page and every product page its own fresh connection.
2. A page holds up to 48 products, so Max products is the main lever on cost, and Max result pages per search is there when you want to bound the walk's depth as well. Full details add one more page per product, which is why they are opt in and carry their own charge.

Buyer opinions

Opinions are a real, fully published feature on this marketplace, and this actor collects them. Per product you get the overall rating, the opinion count and the count at each star level; per opinion you get the rating, the text, the date, the reviewer's country, the helpful-vote count, the photo addresses and the number of attached videos. Opinion authors are not returned: the marketplace does not publish a name or profile with a product opinion, so there is no author field to return and none is invented.

Opinions are published on the product page itself (the first page of them, alongside the rating summary). That has two consequences, both disclosed up front:

• turning on Fetch buyer opinions opens each product's page, exactly as full details does, so it is charged the same Detail enrichment event per product whose page was read - the two toggles are one page read, and either one alone is enough to open it;
• what is available is the page's own first page of opinions, so maxReviewsPerProduct caps rows that are already on the page rather than paging a deeper feed.

The marketplace's standalone opinion-feed URL was probed while building this and it no longer serves opinions (it returns an empty shell for every product, including ones with tens of thousands of published opinions), so the actor reads opinions where the marketplace actually publishes them: the product page.

Incremental mode and resume

Two different things, both in the Resume & recurring updates section.

Resume from a previous run continues one specific interrupted run. Paste the run or dataset id and the products already collected there are skipped, so they are neither returned nor billed again. The walk still starts at the first result page and steps over the products that run already collected, so if you set Max result pages per search to a number, raise it when you resume a deep pull: the pages the previous run covered still count against it. Left at its default of 0 it does not bound the resumed walk at all.

Incremental mode is for recurring monitoring. Turn it on and schedule the actor: the first run returns everything as NEW, and later runs return only what changed, marked NEW, UPDATED or REAPPEARED, with changedFields naming exactly which fields moved. State is kept per keyword-and-filter setup, so two different searches never mix baselines; use State key to name a campaign or to deliberately share one.

• Emit unchanged also returns products that did not change, marked UNCHANGED. This returns, and bills, extra rows you already have.
• Emit expired also returns products that have disappeared, marked EXPIRED. These are only produced after a run has fully scanned the tracked search, so never when Max products capped the run, never after a resume, and never when a run collected nothing.

reviews is excluded from change detection on purpose: a popular product carries hundreds of opinion rows, and tracking every one of them would rewrite the record on every new opinion and would put the whole opinion corpus into the saved state. Nothing is lost: rating, reviewCount and ratingBreakdown are all tracked, so a new or deleted opinion still marks the product UPDATED and still names those fields in changedFields.

Scope: Brazil only

This actor covers the Brazilian storefront only, and that is deliberate rather than an oversight.

Mercado Libre runs one platform behind per-country storefronts. Verified live while building this actor: the same catalogue backend serves every country, with the site prefix carrying the country (MLB Brazil, MLA Argentina, MLM Mexico, MLC Chile, MCO Colombia, MLU Uruguay), and the same category numbering resolves on all of them. The other storefronts are also behind the same connection gate, pinned to their country.

So a multi-country build is feasible but is a different actor: it needs a residential connection per country, its own per-country catalogue and price validation, and its own currency handling. Nothing here is speculative about markets that were not tested. If you want another Mercado Libre country covered, ask and it can be built and verified properly.

Send results into your apps (MCP connectors)

Optionally pipe results into the apps you already use, through Model Context Protocol (MCP) connectors. Authorize a connector under Apify, Settings, API & Integrations, then select it in mcpConnectors. Notion, Linear, Airtable and Apify are supported. For Notion, also set notionParentPageUrl and each product becomes a page under it; the other connectors get a best-effort write or a digest.

Each connector receives a condensed, human-readable summary per product. The complete record always stays in the Apify dataset. maxNotifyListings caps how many products are written per connector and never affects the dataset output.

Input	What it does
mcpConnectors	The connectors to send results to. Leave empty to skip the export entirely
notionParentPageUrl	URL or id of the Notion page the item pages are created under. Required for the Notion connector, ignored by the others
maxNotifyListings	Cap on products written to each connector per run. Does not affect the dataset

Pricing

You are charged for:

• Product result for each product returned.
• Detail enrichment, once per product whose page is opened. That happens when Fetch full details is on, and also when Fetch buyer opinions is on, because opinions are published on the product page. It buys the description, the full specification table, variants with their own prices, available stock, seller reputation, the complete image gallery and the published opinions. With both toggles off nothing is charged for it, including a pasted product link, which returns its full record for the product-result price alone.
• Actor start, once per run.

Suppressed rows are never charged. In incremental mode, a product whose detail page was read but whose record turned out unchanged is not billed for either the row or the enrichment.

Limits and behaviour

• Max products is the run's one hard cap and is always applied. Max result pages per search is optional and unlimited by default (0), so the walk goes as deep as the marketplace serves and stops on Max products, on a page that returns nothing new, or on an internal 400-page safety stop. Set it to a number when you want a shallower, cheaper pull.
• Sponsored placements are dropped: they are not part of the result set you asked for, they repeat across pages, and billing you for advertising would be wrong.
• If product pages start being refused mid-run, full details are switched off for the rest of the run and the remaining products come back with their catalogue fields only, uncharged for enrichment, rather than grinding through a paid connection.