Mercado Libre

Mercado Libre Search API

Search Mercado Libre listings in Mexico, Brazil (Mercado Livre), Argentina or Colombia by keyword or seller, with condition, price range, discount, free shipping, Full fulfillment, official store and interest-free installment filters, sorted by relevance or price. Each row carries price, list price and discount, installments, seller and official-store flag where shown, rating, units sold as a lower bound, shipping flags, a sponsored flag and catalog ids. About 48 listings per page, up to 42 pages. Costs 2 credits per request.

POST/api/v1/mercadolibre/search

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your Scavio API key (e.g. Bearer sk_live_your_key).

Body

application/json

countryenum<string>required

The Mercado Libre site to search. Chile is not supported.

Example: mx

mx — Mexico (mercadolibre.com.mx), prices in MXN.
br — Brazil, Mercado Livre (mercadolivre.com.br), prices in BRL.
ar — Argentina (mercadolibre.com.ar), prices in ARS.
co — Colombia (mercadolibre.com.co), prices in COP.

querystring

Keywords, 1-200 characters. Pass at least one of query, seller_id or seller_nickname. Mercado Libre may narrow a query to a category, brand or line on its own; auto_applied_filters lists what it applied.

Example: iphone 15

seller_idstring

Only this seller's listings: the numeric id Product returns as seller.seller_id. Combines with query, filters, sort and page.

Example: 527927603

seller_nicknamestring

A seller's public nickname. Returns the seller's first page of listings without filters, plus their seller_id; use seller_id for filters, sort and further pages.

Example: MERCADOLIBRE ELECTRONICA_MX

conditionenum<string>

Item condition. Without it, Mercado Libre may show new items only for some queries (listed in auto_applied_filters).

Example: used

new — New.
used — Used.
refurbished — Refurbished.
open_box — Open box.

min_priceinteger

Minimum price in the country's currency (MXN, BRL, ARS or COP).

Example: 5000

max_priceinteger

Maximum price in the country's currency. Must not be below min_price.

Example: 30000

min_discountenum<integer>

Only listings at least this many percent off.

Example: 20

5 — 5% off or more.
10 — 10% off or more.
15 — 15% off or more.
20 — 20% off or more.
25 — 25% off or more.
30 — 30% off or more.
40 — 40% off or more.

free_shippingbooleandefault:false

Only listings with free shipping.

Example: true

full_fulfillmentbooleandefault:false

Only listings shipped by Mercado Libre Full fulfillment.

Example: true

official_stores_onlybooleandefault:false

Only listings from official brand stores.

Example: true

interest_free_installmentsbooleandefault:false

Only listings payable in interest-free installments (meses sin intereses, parcelas sem juros).

Example: true

sortenum<string>default:relevance

Result order. Mercado Libre offers no newest or best-selling sort.

Example: price_asc

relevance — Mercado Libre's relevance order.
price_asc — Price, low to high.
price_desc — Price, high to low.

pageintegerdefault:1

Results page, 1-42, about 48 listings per page.

Example: 2

Notes

About 2,000 results per query. Mercado Libre serves about 48 listings per page and up to 42 pages for any one query. total and total_pages tell you how many match; in the captured example, "iphone 15" in Mexico matched 938 listings over 20 pages. To read more than 2,000, slice the query by min_price/max_price bands, condition or seller_id and run one search per slice.

Units sold are lower bounds. sold_quantity_min is the bucket Mercado Libre shows (1000 means "+1000 sold"), not an exact count, and sold_label carries the site's own text when the card shows it. Both are null when the card shows no sales figure.

Sort by relevance or price only. There is no newest or best-selling sort. For the top sellers in a category, use Best Sellers (Mexico, Argentina and Colombia).

Brazil search prices are usually the Pix price. On Mercado Livre the price on a search row is usually the Pix price, about 5% below the regular price. Product returns the regular price and usually lists the Pix offer under promotions. On 11 October 2026 an iPhone 15 showed R$4,009 in search and R$4,220.84 on Product, so compare like with like before flagging a price change.

Filters Mercado Libre applies on its own. A query can be narrowed to a category, brand or line without being asked (the captured "iphone 15" search was narrowed to brand Apple and line iPhone 15), and in Brazil and Argentina some queries show new items only unless you pass condition. auto_applied_filters lists what was applied automatically, and available_filters lists the facets with their result counts.

seller has the seller name and official-store flag only where the result card shows them (null otherwise). Product returns the buy-box seller in full, with seller_id and reputation.
Sponsored listings are flagged in place with sponsored: true and keep their position.
A query with no results returns 200 with count: 0 and is billed. An unknown seller nickname returns 404 and is billed. Temporary failures (502/503) are never billed.
category_id and category_path feed Best Sellers; product_id and item_id feed Product, Reviews and Questions.

Request

from scavio import ScavioClient

client = ScavioClient(api_key="sk_live_your_key")

res = client.mercadolibre.search("iphone 15", country="mx", condition="new", free_shipping=True)

data = res["data"]
print(data["total"], "matches,", data["total_pages"], "pages")
for r in data["results"]:
    print(r["position"], r["title"], r["price"], r["currency"], r["sold_quantity_min"], r["sponsored"])

Response

"country": "mx",

"site_id": "MLM",

"query": "iphone 15",

"seller_id": null,

"seller_nickname": null,

"page": 1,

"page_size": 48,

"total": 938,

"total_pages": 20,

"sort": "relevance",

"category_id": "MLM1055",

"count": 48,

"response_time": 11026

}

from scavio import ScavioClient client = ScavioClient(api_key="sk_live_your_key") res = client.mercadolibre.search("iphone 15", country="mx", condition="new", free_shipping=True) data = res["data"] print(data["total"], "matches,", data["total_pages"], "pages") for r in data["results"]: print(r["position"], r["title"], r["price"], r["currency"], r["sold_quantity_min"], r["sponsored"])