# MercadoLibre Scraper - Products Reviews Q\&A Sellers Inventory (`karamelo/mercadolibre-scraper-products-reviews-qa-sellers`) Actor

Extract products, reviews, buyer Q\&A, and seller storefront profiles with detailed datapoints from MercadoLibre LATAM: AR, BO, BR, CL, CO, CR, DO, EC, GT, HN, MX, NI, PA, PY, PE, SV, UY y VE

- **URL**: https://apify.com/karamelo/mercadolibre-scraper-products-reviews-qa-sellers.md
- **Developed by:** [karamelo](https://apify.com/karamelo) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 result items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## MercadoLibre Products, Reviews, Q\&A and Sellers

Scrape public MercadoLibre and MercadoLivre search listings, product pages, reviews, buyer questions, and seller storefronts across 18 Latin American marketplaces. Use the actor for regional price monitoring, competitive research, product discovery, seller analysis, promotion tracking, e-commerce automation, and datasets for AI workflows.

The actor keeps the established four-mode contract: `search`, `product`, `seller`, and `reviews`. It collects public MercadoLibre information and returns the results through the Dataset using the documented input and output fields.

### What this actor extracts

Depending on the selected mode and what the public page exposes, records can include:

- Product titles, URLs, thumbnails, images, brands, descriptions, conditions, SKU values, attributes, variations, and breadcrumbs.
- Current and previous prices, discounts, currency, installments, availability, shipping, returns, and promotions.
- Ratings, rating counts, review counts, inline reviews, buyer questions, and seller answers.
- Seller IDs, names, reputation, power-seller status, official-store details, and storefront metadata.
- Seller profiles, catalog items, featured items, menu corridors, banners, logos, and public storefront descriptions.
- Stable identifiers such as `publicationId`, `productId`, `catalogProductId`, `userProductId`, `variationId`, `sellerId`, and `officialStoreId`.

Availability depends on the marketplace, category, listing, country, page type, and current public HTML. Missing values are returned as `null` where the schema allows it; arrays and nested objects remain in the same flat dataset record rather than becoming separate records.

### Use cases

#### Price, discount, and promotion monitoring

Schedule the same search across countries and compare `currentPrice`, `previousPrice`, `discount`, `installments`, and `promotions`. Keep `scrapedAt`, `countryCode`, `resultPosition`, and `productUrl` to build a historical series.

#### Competitive research and share of search

Use `searchSort`, `resultPosition`, `resultType`, `brand`, `sellerName`, `sellerReputation`, and `isOfficialStore` to study product visibility and seller competition. Run once with sponsored listings excluded and again with them included when you need the commercial view.

#### Product research and demand signals

Search across marketplaces and inspect titles, ratings, review counts, shipping signals, availability, categories, and seller context. Narrow the keyword or split countries into separate runs when you need comparable regional samples.

#### Catalog enrichment and matching

Search mode can add product fields to selected listing records. Product and catalog identifiers help relate multiple listings to the same product family, while product URLs and seller IDs support matching across exports.

#### Seller and storefront analysis

Seller mode emits a storefront profile when enabled, catalog rows, and optional featured-item rows. Use it for brand monitoring, assortment analysis, seller discovery, and public storefront comparisons.

#### Automation and AI datasets

Send the Dataset to spreadsheets, databases, BI tools, alerting systems, RAG pipelines, or AI agents. Use the Apify API, official clients, webhooks, schedules, or MCP to connect the actor to an existing workflow.

### Quick start

1. Open `karamelo/mercadolibre-scraper-products-reviews-qa-sellers` in Apify.
2. Choose `Scraping Mode`.
3. Enter a `Search Query` for Search mode, or provide product/seller URLs for the URL-based modes.
4. Select the `Target Marketplace` and, for Search mode, a `Search Sort Order`.
5. Set `Max Search Pages` for Search mode, or `Max Seller Pages` for Seller mode. These limits are independent.
6. Turn on `Scrape Product Details` only when enrichment is needed. `Max Search Items` then controls how many search rows receive additional product fields; it does not cap the listing records collected from each page.
7. In Reviews mode, use `Max Reviews` to cap the total review records emitted by the run.
8. Start the run and open the Dataset when it finishes.

### Input configuration

The Console starts with the ungrouped fields in this order: Scraping Mode, Search Query, Target Marketplace, Search Sort Order, Max Search Pages, and Include Sponsored Listings. Product URLs is inside Product mode options, followed by the product-detail switches. The remaining fields are grouped into Search mode options, Product mode options, Seller mode options, Advanced, and Reviews mode options.

| Field | Type | Group | Description |
| --- | --- | --- | --- |
| `mode` | string | Visible | Select `search`, `product`, `seller`, or `reviews`; the dropdown labels are Search mode, Product URLs mode, Seller mode, and Reviews mode. |
| `searchQuery` | string | Visible | Keyword used to build a Search mode URL. |
| `country` | string | Visible | Two-letter marketplace code used for the domain, site ID, language context, and currency. |
| `searchSort` | string | Visible | Search order: `relevance`, `price_asc`, or `price_desc`. |
| `maxSearchPages` | integer | Visible | Search pages to inspect, from 1 to 20. Search is page-bounded rather than item-bounded. |
| `includePromoted` | boolean | Visible | Include sponsored or promoted cards in Search mode. |
| `scrapeProductDetails` | boolean | Search mode options | Add available product fields to selected search rows. |
| `maxSearchItems` | integer | Search mode options | When enrichment is enabled, maximum search products to open for detail enrichment, from 1 to 5,000. It does not limit listing rows collected from a page. |
| `productUrls` | string array | Product mode options | Product URLs used by Product and Reviews modes, up to 100. The Console supports Add, Bulk edit, and text-file upload with one URL per line. |
| `includeReviews` | boolean | Product mode options | Keep inline reviews in Product records, or enable review-record output in Reviews mode. |
| `includeQuestions` | boolean | Product mode options | Keep buyer questions and seller answers in Product records. |
| `includeVariations` | boolean | Product mode options | Keep public color, size, storage, or other product variations. |
| `sellerUrls` | string array | Seller mode options | Seller storefront or seller-listing URLs used by Seller mode, up to 50. |
| `sellerMaxPages` | integer | Seller mode options | Seller storefront pages to inspect, from 1 to 20. This is independent from `maxSearchPages` / Max Search Pages. |
| `includeSellerProfile` | boolean | Seller mode options | Emit one storefront profile record before seller catalog rows. |
| `includeFeaturedItems` | boolean | Seller mode options | Emit an additional featured-item record when public storefront cards are available. |
| `startUrls` | string array | Advanced | Direct search, product, review, or seller URLs that supplement the mode-specific fields. |
| `maxConcurrency` | integer | Advanced | Maximum parallel product or seller work items, from 1 to 8. |
| `reviewRating` | string | Reviews mode options | Selected star rating for Reviews mode: `all`, `1`, `2`, `3`, `4`, or `5`. |
| `reviewOrder` | string | Reviews mode options | Review ordering: `relevance` or `dateCreated`. |
| `maxReviews` | integer | Reviews mode options | Maximum total review records emitted in Reviews mode after filtering, from 1 to 5,000. |

#### Input defaults

| Field | Default |
| --- | --- |
| `mode` | `search` |
| `searchQuery` | `zapatillas` |
| `country` | `AR` |
| `searchSort` | `relevance` |
| `maxSearchPages` | `1` |
| `includePromoted` | `false` |
| `scrapeProductDetails` | `false` |
| `maxSearchItems` | `5` |
| `productUrls` | `["https://www.mercadolibre.com.ar/apple-iphone-16-128-gb-negro-distribuidor-autorizado/p/MLA1040287808"]` |
| `includeReviews` | `true` |
| `includeQuestions` | `true` |
| `includeVariations` | `true` |
| `sellerUrls` | `["https://listado.mercadolibre.com.ar/tienda/xiaomi"]` |
| `sellerMaxPages` | `1` |
| `includeSellerProfile` | `true` |
| `includeFeaturedItems` | `false` |
| `startUrls` | `[]` |
| `maxConcurrency` | `8` |
| `reviewRating` | `all` |
| `reviewOrder` | `relevance` |
| `maxReviews` | `15` |

The Advanced group contains the optional `startUrls` and `maxConcurrency` controls. Product URL uploads use the same documented URL list as Add and Bulk edit entries.

#### Search limits and enrichment behavior

Search mode processes up to `maxSearchPages` pages. If `scrapeProductDetails` is off, `Max Search Items` is not used. If enrichment is on, `maxSearchItems` determines how many listing records receive additional product fields. The remaining listings from the requested pages are still returned as search records.

When enrichment is off, Search mode emits listing-level fields only. When enrichment is on, each successfully enriched selected listing is emitted in place of its original search row and marked with `mode: "product"`. If no additional fields are available, that row remains a listing-only `mode: "search"` record. The enrichment cap does not limit the page-bounded search listing rows.

Product mode returns separate publication and catalog identifiers, seller identity and reputation, power-seller status, official-store status, stock, condition, ratings, prices, shipping, promotions, category/domain, and product attributes when available. Seller mode processes up to `sellerMaxPages` pages per seller URL and keeps this page limit separate from Search mode's `maxSearchPages`. Reviews mode emits at most `maxReviews` review records across the run after applying `reviewRating` and `reviewOrder`; the default is 15. Neither mode is controlled by the Search mode enrichment count.

### Supported marketplaces

Use the two-letter code in `country`. The actor maps it to the correct MercadoLibre or MercadoLivre domain, site ID, and currency.

| Country | Code | Domain | Currency |
| --- | :---: | --- | --- |
| Argentina | `AR` | `mercadolibre.com.ar` | ARS |
| Bolivia | `BO` | `mercadolibre.com.bo` | BOB |
| Brazil | `BR` | `mercadolivre.com.br` | BRL |
| Chile | `CL` | `mercadolibre.cl` | CLP |
| Colombia | `CO` | `mercadolibre.com.co` | COP |
| Costa Rica | `CR` | `mercadolibre.co.cr` | CRC |
| Dominican Republic | `DO` | `mercadolibre.com.do` | DOP |
| Ecuador | `EC` | `mercadolibre.com.ec` | USD |
| Guatemala | `GT` | `mercadolibre.com.gt` | GTQ |
| Honduras | `HN` | `mercadolibre.com.hn` | HNL |
| Mexico | `MX` | `mercadolibre.com.mx` | MXN |
| Nicaragua | `NI` | `mercadolibre.com.ni` | NIO |
| Panama | `PA` | `mercadolibre.com.pa` | USD |
| Paraguay | `PY` | `mercadolibre.com.py` | PYG |
| Peru | `PE` | `mercadolibre.com.pe` | PEN |
| El Salvador | `SV` | `mercadolibre.com.sv` | USD |
| Uruguay | `UY` | `mercadolibre.com.uy` | UYU |
| Venezuela | `VE` | `mercadolibre.com.ve` | VES |

For regional comparisons, run one task per country so currency, domain, language, ranking, and public commercial conditions remain explicit.

### Scraping modes

#### Search mode

Enter a keyword and select a marketplace. Search results are processed page by page. Choose the order with `searchSort`:

- `relevance`: MercadoLibre's default order;
- `price_asc`: lowest price first;
- `price_desc`: highest price first.

Each unique listing record can include title, brand, thumbnail, current and previous price, discount, rating, shipping, seller context, identifiers, ranking, and search context. Sponsored cards are excluded by default. When enrichment is enabled, selected rows are returned with `mode: "product"` and can also include product details such as description, condition, images, attributes, variations, questions, reviews, returns, and seller data when available.

#### Product mode

Provide one or more product URLs. Product mode emits a full product record per successfully processed URL, including title, description, brand, condition, SKU, image gallery, prices, discount, currency, stock, ratings, installments, shipping, returns, seller identity and reputation, official-store status, attributes, variations, inline reviews, questions, and breadcrumbs when available.

#### Reviews mode

Provide product URLs. Reviews mode emits one flat record per public review available for each supplied product URL. The product identifier in each URL is used as the review target, so Reviews mode does not emit a Product record. Use `reviewRating` to select a star rating, `reviewOrder` to request relevance order or newest-first order, and `maxReviews` to cap the total review records emitted by the run. The default maximum is 15; deeper review coverage depends on what the public marketplace response serves.

#### Seller mode

Provide seller storefront or seller-listing URLs; the default is `https://listado.mercadolibre.com.ar/tienda/xiaomi`. Seller mode follows up to `sellerMaxPages` pages per seller URL and can emit one profile record per seller, catalog item rows, and optional featured corridor rows. Profile records can include the storefront name, identifiers, followers, public description, images, and menu links when available.

### Input examples

#### Search with price sorting and enrichment

```json
{
  "mode": "search",
  "searchQuery": "zapatillas deportivas",
  "country": "AR",
  "searchSort": "price_asc",
  "maxSearchPages": 3,
  "includePromoted": false,
  "scrapeProductDetails": true,
  "maxSearchItems": 5
}
```

This returns listing records from all three selected pages. At most five of those rows receive additional product fields.

#### Product details

```json
{
  "mode": "product",
  "country": "MX",
  "productUrls": [
    "https://www.mercadolibre.com.mx/apple-iphone-17-pro-256-gb-azul-profundo/p/MLM55308781"
  ],
  "includeReviews": true,
  "includeQuestions": true,
  "includeVariations": true
}
```

#### Reviews with a rating filter

```json
{
  "mode": "reviews",
  "country": "MX",
  "productUrls": [
    "https://www.mercadolibre.com.mx/apple-iphone-17-pro-256-gb-azul-profundo/p/MLM55308781"
  ],
  "reviewRating": "4",
  "reviewOrder": "dateCreated",
  "maxReviews": 25
}
```

#### Seller storefront

```json
{
  "mode": "seller",
  "country": "AR",
  "sellerUrls": [
    "https://listado.mercadolibre.com.ar/tienda/xiaomi/"
  ],
  "sellerMaxPages": 2,
  "includeSellerProfile": true,
  "includeFeaturedItems": true
}
```

### Output dataset

Every record includes `mode` and `scrapedAt`. Search, product, and review records also include their marketplace and product context when available. Dataset results are shown directly in the default display with the declared fields.

Search rows use `mode: "search"`. If enrichment is enabled, the selected rows are returned in their original position with `mode: "product"`; their available search values are retained and the product fields are added where available.

#### Listing and product fields

Search records use this exact public structure: `mode`, `thumbnailUrl`, `currency`, `currentPrice`, `previousPrice`, `discount`, `title`, `installments`, `promotions`, `soldQuantity`, `freeShipping`, `searchKeyword`, `rating`, `reviewCount`, `productUrl`, `shipping`, `highlights`, `countryCode`, `siteId`, `resultPosition`, `totalResults`, `publicationId`, `catalogProductId`, `userProductId`, `variationId`, `isPricePerQuantity`, `isInternationalPurchase`, `shipsFrom`, `inStock`, `sellerName`, `isOfficialStore`, `officialStoreName`, `sku`, `resultType`, `isPromoted`, `availableIn`, `brand`, `categoryId`, `domainId`, `sellerId`, `vertical`, `verticalId`, `location`, and `scrapedAt`. Search prices and `totalResults` are numeric when available; `discount` is the public label such as `"6% OFF"`; unavailable optional values are `null` or empty strings according to the field type.

Product records can additionally include `images`, `description`, `availability`, `inStock`, `condition`, `breadcrumbs`, `attributes`, `variations`, `reviews`, `questions`, `returnPolicy`, `sellerReputation`, `sellerPowerStatus`, and relevant vehicle fields. On Product pages, `reviewCount` and `ratingCount` use the public total count when the page exposes it; Search listing counts may differ because they describe the listing context.

#### Review and seller fields

Reviews mode uses `reviewId`, `reviewRating`, `reviewText`, `reviewDate`, `reviewCountry`, and `reviewLikes`. Seller records can include `sellerSlug`, `sellerProfileUrl`, `sellerListingUrl`, `shopId`, `shopName`, `shopType`, `officialStoreId`, `totalFollowers`, `bannerUrl`, `logoUrl`, `storefrontUrl`, `sellerDescription`, `menuCorridors`, `corridorName`, and `corridorUrl` when available.

#### Example search record

```json
{
  "mode": "search",
  "thumbnailUrl": "https://http2.mlstatic.com/D_NQ_NP_979958-MLA105250865291_012026-O.webp",
  "currency": "CLP",
  "currentPrice": 939990,
  "previousPrice": 999990,
  "discount": "6% OFF",
  "title": "Apple iPhone 17 (256 GB) - Azul neblina - Distribuidor Autorizado",
  "installments": "12 cuotas de 78332 sin interés",
  "promotions": "",
  "soldQuantity": 500,
  "freeShipping": true,
  "searchKeyword": "iphone",
  "rating": 4.9,
  "reviewCount": 0,
  "productUrl": "https://www.mercadolibre.cl/apple-iphone-17-256-gb-azul-neblina-distribuidor-autorizado/p/MLC1055308852",
  "shipping": "Llega gratis hoy Enviado por FULL",
  "highlights": "APPLE TIENDA OFICIAL",
  "countryCode": "CL",
  "siteId": "MLC",
  "resultPosition": 1,
  "totalResults": 3949,
  "publicationId": "MLC1694275125",
  "catalogProductId": "MLC1055308852",
  "userProductId": "MLCU3409642961",
  "variationId": "MLC1055308852",
  "isPricePerQuantity": false,
  "isInternationalPurchase": false,
  "shipsFrom": "",
  "inStock": null,
  "sellerName": "Apple Tienda oficial",
  "isOfficialStore": true,
  "officialStoreName": "Apple Tienda oficial",
  "sku": "MLC1055308852",
  "resultType": "ORGANIC",
  "isPromoted": false,
  "availableIn": "",
  "brand": "",
  "categoryId": "MLC1055",
  "domainId": "MLC-CELLPHONES",
  "sellerId": "",
  "vertical": "CORE",
  "verticalId": "CORE",
  "location": "",
  "scrapedAt": "2026-08-20T00:00:00.000Z"
}
```

Arrays and nested objects remain inside each flat Dataset record.

### Complete output property dictionary

| Group | Fields | Use |
| --- | --- | --- |
| Product | `title`, `productUrl`, `thumbnailUrl`, `images`, `brand`, `description`, `condition`, `sku` | Product discovery and catalog enrichment. |
| Price | `currency`, `currentPrice`, `previousPrice`, `discount`, `installments` | Regional price and discount history. |
| Search context | `resultPosition`, `resultType`, `isPromoted`, `searchKeyword`, `totalResults`, `soldQuantity` | Result ranking and search analysis. |
| Shipping | `freeShipping`, `shipping`, `shippingDetails`, `shipsFrom`, `availability`, `inStock`, `returnPolicy` | Delivery, availability, and returns analysis. |
| Reviews and Q\&A | `rating`, `ratingCount`, `reviewCount`, `reviews`, `questions`, `reviewRating`, `reviewText`, `reviewDate` | Product quality and review monitoring. |
| Seller | `sellerId`, `sellerName`, `sellerReputation`, `sellerPowerStatus`, `isOfficialStore`, `officialStoreName` | Seller comparison and official-store analysis. |
| Taxonomy | `breadcrumbs`, `categoryId`, `domainId`, `vertical`, `verticalId`, `location`, `kind` | Segmentation by category, domain, and record type. |
| Identifiers | `siteId`, `publicationId`, `productId`, `catalogProductId`, `userProductId`, `variationId`, `sku` | Relationships and historical comparison. |
| Seller profile | `sellerSlug`, `sellerProfileUrl`, `sellerListingUrl`, `shopId`, `shopName`, `shopType`, `officialStoreId`, `totalFollowers`, `bannerUrl`, `logoUrl`, `storefrontUrl`, `sellerDescription`, `menuCorridors`, `corridorName`, `corridorUrl` | Public storefront information. |
| Audit | `mode`, `countryCode`, `scrapedAt` | Record type, marketplace, and collection time. |

### Pricing

This Actor uses pay-per-event pricing. Platform usage is included.

| Output record | Charge event | Price |
|---|---|---:|
| Search result | `search_item` | $2.00 per 1,000 records |
| Product result, including Search enrichment | `product_detail` | $6.00 per 1,000 records |
| Review result | `review_item` | $1.00 per 1,000 records |
| Seller profile, listing, or featured result | `seller_item` | $2.00 per 1,000 records |

Every saved result record is charged once according to the result type above. Search enrichment records are charged as product results when they are emitted with `mode: "product"`; review and seller records are charged as their respective result types. Seller catalog records are search-style results limited to one seller, so `seller_item` uses the same rate as `search_item`.

### Apify API

Replace `APIFY_TOKEN` with your Apify token. Use the actor name exactly as published: `karamelo/mercadolibre-scraper-products-reviews-qa-sellers`.

#### JavaScript / Node.js

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor(
  'karamelo/mercadolibre-scraper-products-reviews-qa-sellers',
).call({
  mode: 'search',
  searchQuery: 'zapatillas deportivas',
  country: 'AR',
  searchSort: 'price_asc',
  maxSearchPages: 3,
  includePromoted: false,
  scrapeProductDetails: true,
  maxSearchItems: 5,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

Install the client with:

```bash
npm install apify-client
```

#### Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])

run = client.actor(
    'karamelo/mercadolibre-scraper-products-reviews-qa-sellers'
).call(run_input={
    'mode': 'search',
    'searchQuery': 'zapatillas deportivas',
    'country': 'AR',
    'searchSort': 'price_asc',
    'maxSearchPages': 3,
    'includePromoted': False,
})

items = list(client.dataset(run['defaultDatasetId']).iterate_items())
print(items)
```

Install the client with:

```bash
pip install apify-client
```

#### cURL: synchronous dataset response

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/karamelo~mercadolibre-scraper-products-reviews-qa-sellers/run-sync-get-dataset-items?format=json&clean=true" \
  -H "Authorization: Bearer APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "search",
    "searchQuery": "zapatillas deportivas",
    "country": "AR",
    "searchSort": "price_asc",
    "maxSearchPages": 3,
    "includePromoted": false
  }'
```

#### cURL: asynchronous run

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/karamelo~mercadolibre-scraper-products-reviews-qa-sellers/runs" \
  -H "Authorization: Bearer APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "search",
    "searchQuery": "zapatillas deportivas",
    "country": "AR",
    "searchSort": "price_asc",
    "maxSearchPages": 3,
    "includePromoted": false
  }'
```

After the run completes, use its `defaultDatasetId` to retrieve JSON, CSV, or another Dataset export format supported by Apify.

### MCP and AI agents

Apify MCP can expose this actor to compatible clients such as ChatGPT, Claude, Cursor, Codex, and other MCP-enabled tools. Complete Apify authorization when the client requests it.

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=karamelo/mercadolibre-scraper-products-reviews-qa-sellers"
    }
  }
}
```

Example agent prompt:

```text
Run karamelo/mercadolibre-scraper-products-reviews-qa-sellers for
"notebook gamer" in Mexico (MX), inspect 3 search pages, sort by lowest price,
exclude sponsored listings, and return title, current price, currency, discount,
shipping, rating, seller, and product URL.
```

Example JavaScript context preparation:

```javascript
const contextForAgent = items.map((item) => ({
  mode: item.mode,
  title: item.title,
  currentPrice: item.currentPrice,
  currency: item.currency,
  discount: item.discount,
  freeShipping: item.freeShipping,
  rating: item.rating,
  seller: item.sellerName,
  productUrl: item.productUrl,
}));

console.log(JSON.stringify(contextForAgent));
```

### Automation and integrations

- **Schedules:** run the same query hourly, daily, or weekly to build history.
- **Webhooks:** notify another service when a run succeeds or fails.
- **Make and Zapier:** connect datasets to spreadsheets, databases, email, or Slack.
- **Google Sheets and Excel:** build price, promotion, and seller dashboards from Dataset exports.
- **Data warehouses:** load JSON or JSONL into BigQuery, Snowflake, PostgreSQL, or another pipeline.
- **AI agents:** connect through MCP or consume the Dataset with JavaScript or Python.

### Consistent-results recommendations

- Start with one or two pages to validate the query and fields.
- Use `includePromoted: false` for organic-ranking analysis and `true` for the full commercial view.
- Keep `countryCode`, `searchSort`, `resultPosition`, `productUrl`, and `scrapedAt` in historical comparisons.
- Interpret `currentPrice` together with `currency`; do not mix ARS, BRL, MXN, and other currencies without conversion.
- Use product, listing, and variation identifiers according to the entity you want to compare.
- Check nullable fields before calculating averages or sending records to production.
- Use a reasonable page count and schedule frequency for your data need.

### Limitations

- Search returns public results from the pages processed by `maxSearchPages`; it does not promise the marketplace's full total.
- Search enrichment applies to `maxSearchItems` selected listing rows. Listing rows beyond that count are still returned with their search fields.
- Descriptions, questions, reviews, attributes, availability, shipping, and stock depend on what MercadoLibre publishes for each product.
- Price, sold-count, result totals, shipping, and delivery dates can be rounded, summarized, or absent.
- Category, location, availability, page design, and experiments can change the fields visible in a response.
- A page can produce fewer records when the marketplace hides, duplicates, removes, or blocks results.
- Product and seller pages are public-page targets; no private orders, account history, or unpublished seller data are collected.

### Frequently asked questions

#### Which MercadoLibre countries are supported?

All 18 configured marketplaces are supported: AR, BO, BR, CL, CO, CR, DO, EC, GT, HN, MX, NI, PA, PE, PY, SV, UY, and VE. Use the two-letter code in `country`.

#### Can I compare one product across countries?

Yes. Run a separate task for each `country`, then compare the resulting Datasets while retaining `currency`, `countryCode`, `scrapedAt`, and `productUrl`.

#### Can I sort results by price?

Yes. Set `searchSort` to `price_asc` or `price_desc`.

#### Does `maxSearchItems` limit the number of search listings?

No. Search is page-bounded by `maxSearchPages`. When `scrapeProductDetails` is enabled, `maxSearchItems` controls how many listing rows receive additional product fields. It does not remove later listing rows from the Dataset.

#### Can I exclude sponsored listings?

Yes. Set `includePromoted` to `false`. Set it to `true` when sponsored cards should remain in the search output.

#### Do I need to provide login credentials or cookies?

No. The actor is designed for public pages and does not accept or require target-site credentials or cookies.

#### How do I create a price monitor?

Keep `mode`, `searchQuery`, `country`, `searchSort`, `maxSearchPages`, and `includePromoted` consistent across scheduled runs. Compare `currentPrice`, `previousPrice`, `discount`, `promotions`, `resultPosition`, and `scrapedAt` by product or listing identifier.

#### Can I download the results as CSV or Excel?

Yes. Export the Apify Dataset from the Console or use the Dataset items API with a supported `format` such as CSV.

#### Can I use this actor as a product API?

Yes. Run it through the Apify REST API, official JavaScript and Python clients, or MCP. Product and seller URL modes are useful when the input is already known; Search mode is useful when the input is a keyword.

### Responsible use and legal notice

Collect only public information and use it according to applicable terms, privacy rules, and marketplace policies. Avoid unnecessary personal data and excessive request loads. This Karamelo actor is independent and is not affiliated with, sponsored by, or endorsed by MercadoLibre, MercadoLivre, or Apify.

### Support

For troubleshooting, share the search query, country, mode, page count, search sort, sponsored-listing setting, run ID, and an example of the unexpected field. Never share tokens or other secrets.

# Actor input Schema

## `mode` (type: `string`):

Search listings, extract product details, inspect seller storefronts, or emit review records.

## `searchQuery` (type: `string`):

Keyword used to build a MercadoLibre search URL when Scraping Mode is search. Search records use this value as searchKeyword.

## `country` (type: `string`):

Marketplace country code used for the search domain, language, site ID, and currency. Search records expose the same code as countryCode.

## `searchSort` (type: `string`):

Choose how MercadoLibre orders search results. The selected order is retained while paginating Search mode.

## `maxSearchPages` (type: `integer`):

Maximum number of paginated search result pages to inspect.

## `includePromoted` (type: `boolean`):

Include sponsored or promoted cards when Scraping Mode is search. Search records always expose the public isPromoted flag.

## `scrapeProductDetails` (type: `boolean`):

Open selected search result pages and merge available product details into the same listing records.

## `maxSearchItems` (type: `integer`):

When Scrape Product Details is enabled in Search mode, maximum number of search products to open and enrich. This does not limit listing records collected from each page.

## `productUrls` (type: `array`):

MercadoLibre product URLs used by Product and Reviews modes. Product and Reviews modes require at least one product URL; Search Query is not used there. Add URLs individually, bulk edit them, or upload a text file containing one URL per line.

## `includeReviews` (type: `boolean`):

Keep review data in product records when it is available on the public page.

## `includeQuestions` (type: `boolean`):

Keep buyer questions and seller answers in product records when available.

## `includeVariations` (type: `boolean`):

Keep public color, size, or storage variation data in product records when available.

## `sellerUrls` (type: `array`):

MercadoLibre seller storefront or seller-listing URLs used by seller mode.

## `sellerMaxPages` (type: `integer`):

Maximum number of seller storefront pages to inspect in Seller mode. This is independent from Max Search Pages.

## `includeSellerProfile` (type: `boolean`):

Write one storefront profile record before seller catalog records.

## `includeFeaturedItems` (type: `boolean`):

Write an additional featured-item record when the public storefront exposes catalog cards.

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

Optional direct URLs to scrape. These can be search, product, review, or seller URLs and supplement the mode-specific URL fields.

## `maxConcurrency` (type: `integer`):

Upper bound for concurrent product or seller page requests.

## `reviewRating` (type: `string`):

Selected star rating to include in Reviews mode. All ratings keeps maximum coverage.

## `reviewOrder` (type: `string`):

Sort order for review records in Reviews mode when the public page exposes review dates.

## `maxReviews` (type: `integer`):

Maximum total review records to emit in Reviews mode for this run, after the rating and sort filters are applied.

## Actor input object example

```json
{
  "mode": "search",
  "searchQuery": "zapatillas",
  "country": "AR",
  "searchSort": "relevance",
  "maxSearchPages": 1,
  "includePromoted": false,
  "scrapeProductDetails": false,
  "maxSearchItems": 5,
  "productUrls": [
    "https://www.mercadolibre.com.ar/apple-iphone-16-128-gb-negro-distribuidor-autorizado/p/MLA1040287808"
  ],
  "includeReviews": true,
  "includeQuestions": true,
  "includeVariations": true,
  "sellerUrls": [
    "https://listado.mercadolibre.com.ar/tienda/xiaomi"
  ],
  "sellerMaxPages": 1,
  "includeSellerProfile": true,
  "includeFeaturedItems": false,
  "startUrls": [],
  "maxConcurrency": 8,
  "reviewRating": "all",
  "reviewOrder": "relevance",
  "maxReviews": 15
}
```

# Actor output Schema

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

No description

# 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 = {
    "mode": "search",
    "searchQuery": "zapatillas",
    "country": "AR",
    "searchSort": "relevance",
    "productUrls": [
        "https://www.mercadolibre.com.ar/apple-iphone-16-128-gb-negro-distribuidor-autorizado/p/MLA1040287808"
    ],
    "sellerUrls": [
        "https://listado.mercadolibre.com.ar/tienda/xiaomi"
    ],
    "reviewRating": "all",
    "reviewOrder": "relevance"
};

// Run the Actor and wait for it to finish
const run = await client.actor("karamelo/mercadolibre-scraper-products-reviews-qa-sellers").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 = {
    "mode": "search",
    "searchQuery": "zapatillas",
    "country": "AR",
    "searchSort": "relevance",
    "productUrls": ["https://www.mercadolibre.com.ar/apple-iphone-16-128-gb-negro-distribuidor-autorizado/p/MLA1040287808"],
    "sellerUrls": ["https://listado.mercadolibre.com.ar/tienda/xiaomi"],
    "reviewRating": "all",
    "reviewOrder": "relevance",
}

# Run the Actor and wait for it to finish
run = client.actor("karamelo/mercadolibre-scraper-products-reviews-qa-sellers").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 '{
  "mode": "search",
  "searchQuery": "zapatillas",
  "country": "AR",
  "searchSort": "relevance",
  "productUrls": [
    "https://www.mercadolibre.com.ar/apple-iphone-16-128-gb-negro-distribuidor-autorizado/p/MLA1040287808"
  ],
  "sellerUrls": [
    "https://listado.mercadolibre.com.ar/tienda/xiaomi"
  ],
  "reviewRating": "all",
  "reviewOrder": "relevance"
}' |
apify call karamelo/mercadolibre-scraper-products-reviews-qa-sellers --silent --output-dataset

```

## MCP server setup

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

```

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/d3whLkvYV7szCtdUw/builds/4bX7FXD4KbjbmcboT/openapi.json