Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Última atualização em 02/07/2025
Brand Ads
Fluxo técnico recomendado
- Consultar anunciante (advertiser id)
- Consultar campanhas, anuncios e keywords
- Consulta métricas do anunciante, campanhas e keywords
Consultar anunciante
Os anunciantes (advertiser_id) são aqueles que têm um pressuposto para a criação e distribuição de anúncios publicitários, com o objetivo de promover seus produtos ou serviços. Consulte a listagem de anunciantes que têm acesso a um usuário, dependendo do tipo de produto que você deseja (Brand Ads ou Display).
Parâmetros obrigatórios
product_id: tipo de produto. Valores disponíveis: DISPLAY, BADS (Brand Ads).
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -H 'Api-Version: 1'
https://api.mercadolibre.com/advertising/advertisers?product_id=$PRODUCT_IDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -H 'Api-Version: 1'
https://api.mercadolibre.com/advertising/advertisers?product_id=BADSResposta:
{
"advertisers": [
{
"advertiser_id": 000,
"site_id": "MLB",
"advertiser_name": "Advertiser AAA",
"account_name": "MLB - XZY"
},
{
"advertiser_id": 111,
"site_id": "MLM",
"advertiser_name": "Advertiser BBB",
"account_name": "MLM - XYZ"
},
{
"advertiser_id": 222,
"site_id": "MLA",
"advertiser_name": "Advertiser CCC",
"account_name": "MLA - XYZ"
},
{
"advertiser_id": 333,
"site_id": "MLC",
"advertiser_name": "Advertiser DDD",
"account_name": "MLC - XYZ"
}
]
}Campos de resposta
advertiser_id: identificador do anunciante. Você o usará para o restante das solicitações.
site_id: identificador do país. Consulte a nomenclatura dos sites do Mercado Livre e suas respectivas moedas.
advertiser_name: nome do anunciante.
account_name: nome da conta.
Tipos de campanhas
Antes de consultar campanhas, recomendamos conhecer os tipos de campanhas. Além disso, você pode acessar métricas de campanhas a partir de 2023-02-09.
- Automatic: as campanhas automáticas são administradas pelo Mercado Ads. A campanha será executada automaticamente para todos os itens associados ao official_store_id do destination_id enviado e criará palavras-chave, que não poderão ser editadas nem eliminadas, ou seja, o Mercado Ads administrará o inventário do anunciante e atribuirá as melhores palavras-chave para seus anúncios.
- Custom: as campanhas personalizadas são criadas e administradas pelo usuário, onde o anunciante deve fornecer uma lista de itens (mínimo 3, máximo 10) com os quais configurar seu anúncio e as palavras-chave (mínimo 1, máximo 200) que são palavras-chave para buscas em que deseja ser exibido. Depois, poderá editar e excluir essas palavras-chave.
Search campanhas de anunciante
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaignsResposta:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 2
},
"campaigns": [
{
"campaign_id": 1,
"name": "campaign meli 1",
"start_date": "2024-01-01T00:06:22.000Z",
"end_date": "2024-01-01T00:06:22.000Z",
"advertiser_id": 1234,
"campaign_type": "custom",
"status": "active",
"site_id": "MLA",
"official_store_id": 12345,
"destination_id": 12345,
"headline": "esto es un headline",
"budget": {
"amount": 1111111.32,
"currency": "ARS"
},
"cpc": 100.5,
"items": [
{
"campaign_id": 1,
"status": "active",
"item_id": "MLA1178375484"
}
],
"keywords": [
{
"campaign_id": 1,
"type": "custom",
"term": "auto",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]
}
]
}Detalhe de campanha
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_IDResposta:
{
"campaign_id": 1,
"name": "campaign meli 1",
"start_date": "2024-01-01T00:06:22.000Z",
"end_date": "2024-01-01T00:06:22.000Z",
"advertiser_id": 1234,
"campaign_type": "custom",
"status": "active",
"site_id": "MLA",
"official_store_id": 12345,
"destination_id": 12345,
"headline": "esto es un headline",
"budget": {
"amount": 1111111.32,
"currency": "ARS"
},
"cpc": 100.5,
"items": [
{
"campaign_id": 1,
"status": "active",
"item_id": "MLA1178375484"
}
],
"keywords": [
{
"campaign_id": 1,
"keyword_id": 1,
"type": "custom",
"term": "auto",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]
}Consultar anúncios de uma campanha custom
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/items[
{
"campaign_id": 1,
"status": "active",
"item_id": "MLA1178375484"
}
]Consultar keywords da campanha custom
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/keywordsResposta:
[
{
"campaign_id": 1,
"type": "custom",
"term": "auto",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]Consulta de métricas
Métricas da campanha
Parâmetros obrigatórios
date_from: data desde a consulta no formato YYYY-MM-DD.
date_to: data até consulta no formato YYYY-MM-DD.
strategy: tipo da campanha. Valores possíveis: marketplace ou veículos. (novo a partir de 04 de Agosto)
Parâmetros opcionais
limit: por padrão 50.
offset: por padrão 0.
aggregation_type: tipo agregado de dados a serem exibidos. Valores possíveis: daily, total. Por padrão, ele retorna ambos. (excluído a partir de 04 de Agosto)
fields: campos de métrica específicos a serem consultados. (excluído a partir de 04 de Agosto)
Filtros disponíveis (até de 04 de Agosto)
status: estado da campanha. Valores possíveis: active, paused.
destination_id: id de destination da campanha.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&aggregation_type=dailyExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/10101010/brand_ads/campaigns/metrics?date_from=2025-04-01&date_to=2025-04-07&aggregation_type=dailyResposta: Atual (até de 04 de Agosto)
{
"paging": {
"total": 1,
"offset": 0,
"limit": 90
},
"metrics": [
{
"date": "2025-01-07",
"site_id": "MLA",
"currency": "ARS",
"prints": 0,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
],
"summary": {
"site_id": "MLA",
"currency": "ARS",
"prints": 0,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
}Resposta: Nova (a partir de 04 de Agosto)
{
"dashboard": {
"ctr": [
{
"x": "2025-04-01",
"y": 0.02
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 0.01
},
{
"x": "2025-04-04",
"y": 0.01
},
{
"x": "2025-04-05",
"y": 0.01
},
{
"x": "2025-04-06",
"y": 0.01
},
{
"x": "2025-04-07",
"y": 0.01
}
],
"campaignId": [
{
"x": "2025-04-01",
"y": 0
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 0
},
{
"x": "2025-04-04",
"y": 0
},
{
"x": "2025-04-05",
"y": 0
},
{
"x": "2025-04-06",
"y": 0
},
{
"x": "2025-04-07",
"y": 0
}
],
"acos": [
{
"x": "2025-04-01",
"y": 0.00
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 12.69
},
{
"x": "2025-04-04",
"y": 1.98
},
{
"x": "2025-04-05",
"y": 2.99
},
{
"x": "2025-04-06",
"y": 0.00
},
{
"x": "2025-04-07",
"y": 17.26
}
],
"attribution_order_amount": [
{
"x": "2025-04-01",
"y": 0.00
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 789999.00
},
{
"x": "2025-04-04",
"y": 7597994.00
},
{
"x": "2025-04-05",
"y": 4977997.00
},
{
"x": "2025-04-06",
"y": 0.00
},
{
"x": "2025-04-07",
"y": 869013.00
}
],
"attribution_order_conversions": [
{
"x": "2025-04-01",
"y": 0
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 1
},
{
"x": "2025-04-04",
"y": 6
},
{
"x": "2025-04-05",
"y": 3
},
{
"x": "2025-04-06",
"y": 0
},
{
"x": "2025-04-07",
"y": 2
}
],
"prints": [
{
"x": "2025-04-01",
"y": 4528
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 16275
},
{
"x": "2025-04-04",
"y": 16975
},
{
"x": "2025-04-05",
"y": 20429
},
{
"x": "2025-04-06",
"y": 18822
},
{
"x": "2025-04-07",
"y": 20696
}
],
"consumed_budget": [
{
"x": "2025-04-01",
"y": 80047.58
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 100263.18
},
{
"x": "2025-04-04",
"y": 150378.75
},
{
"x": "2025-04-05",
"y": 148986.63
},
{
"x": "2025-04-06",
"y": 149729.73
},
{
"x": "2025-04-07",
"y": 150006.54
}
],
"leads": [
{
"x": "2025-04-01",
"y": 0
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 0
},
{
"x": "2025-04-04",
"y": 0
},
{
"x": "2025-04-05",
"y": 0
},
{
"x": "2025-04-06",
"y": 0
},
{
"x": "2025-04-07",
"y": 0
}
],
"cost_per_clicks": [
{
"x": "2025-04-01",
"y": 650.79
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 396.30
},
{
"x": "2025-04-04",
"y": 496.30
},
{
"x": "2025-04-05",
"y": 480.60
},
{
"x": "2025-04-06",
"y": 479.90
},
{
"x": "2025-04-07",
"y": 438.62
}
],
"clicks": [
{
"x": "2025-04-01",
"y": 123
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 253
},
{
"x": "2025-04-04",
"y": 303
},
{
"x": "2025-04-05",
"y": 310
},
{
"x": "2025-04-06",
"y": 312
},
{
"x": "2025-04-07",
"y": 342
}
],
"keyword": [
{
"x": "2025-04-01",
"y": 0
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 0
},
{
"x": "2025-04-04",
"y": 0
},
{
"x": "2025-04-05",
"y": 0
},
{
"x": "2025-04-06",
"y": 0
},
{
"x": "2025-04-07",
"y": 0
}
],
"cvr": [
{
"x": "2025-04-01",
"y": 0.00
},
{
"x": "2025-04-02",
"y": 0
},
{
"x": "2025-04-03",
"y": 0.00
},
{
"x": "2025-04-04",
"y": 0.01
},
{
"x": "2025-04-05",
"y": 0.00
},
{
"x": "2025-04-06",
"y": 0.00
},
{
"x": "2025-04-07",
"y": 0.00
}
]
},
"metrics": [
{
"date": "2025-04-01",
"metrics": {
"prints": 4528,
"clicks": 123,
"ctr": 0.02,
"cvr": 0.00,
"acos": 0.00,
"attribution_order_conversions": 0,
"attribution_order_amount": 0.00,
"consumed_budget": 80047.58,
"cost_per_clicks": 650.79,
"leads": 0
}
},
{
"date": "2025-04-03",
"metrics": {
"prints": 16275,
"clicks": 253,
"ctr": 0.01,
"cvr": 0.00,
"acos": 12.69,
"attribution_order_conversions": 1,
"attribution_order_amount": 789999.00,
"consumed_budget": 100263.18,
"cost_per_clicks": 396.30,
"leads": 0
}
},
{
"date": "2025-04-04",
"metrics": {
"prints": 16975,
"clicks": 303,
"ctr": 0.01,
"cvr": 0.01,
"acos": 1.98,
"attribution_order_conversions": 6,
"attribution_order_amount": 7597994.00,
"consumed_budget": 150378.75,
"cost_per_clicks": 496.30,
"leads": 0
}
},
{
"date": "2025-04-05",
"metrics": {
"prints": 20429,
"clicks": 310,
"ctr": 0.01,
"cvr": 0.00,
"acos": 2.99,
"attribution_order_conversions": 3,
"attribution_order_amount": 4977997.00,
"consumed_budget": 148986.63,
"cost_per_clicks": 480.60,
"leads": 0
}
},
{
"date": "2025-04-06",
"metrics": {
"prints": 18822,
"clicks": 312,
"ctr": 0.01,
"cvr": 0.00,
"acos": 0.00,
"attribution_order_conversions": 0,
"attribution_order_amount": 0.00,
"consumed_budget": 149729.73,
"cost_per_clicks": 479.90,
"leads": 0
}
},
{
"date": "2025-04-07",
"metrics": {
"prints": 20696,
"clicks": 342,
"ctr": 0.01,
"cvr": 0.00,
"acos": 17.26,
"attribution_order_conversions": 2,
"attribution_order_amount": 869013.00,
"consumed_budget": 150006.54,
"cost_per_clicks": 438.62,
"leads": 0
}
}
],
"summary": {
"prints": 97725,
"clicks": 1643,
"ctr": 0.01,
"cvr": 0.00,
"acos": 5.48,
"attribution_order_conversions": 12,
"attribution_order_amount": 14235003.00,
"consumed_budget": 779412.41,
"cost_per_clicks": 474.38,
"leads": 0
}
}Métricas por campanha e dia
Parâmetros obrigatórios
date_from: data desde a consulta no formato YYYY-MM-DD.
date_to: data da consulta no formato YYYY-MM-DD.
Parâmetros opcionais (até 04 de Agosto)
limit: por padrão 50.
offset: por padrão 0.
fields: campos de métrica específicos a serem consultados.
Parâmetros opcionais (a partir de 04 de Agosto)
aggregation_type: tipo agregado de dados a serem exibidos. Valores possíveis: daily, total. Por padrão, ele retorna ambos.
strategy: tipo da campanha. Valores possíveis: marketplace ou veículos.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/10101010/brand_ads/campaigns/123456/metrics?date_from=2025-05-01&date_to=2025-05-05Resposta: Atual (até de 04 de Agosto)
{
"paging": {
"total": 1,
"offset": 0,
"limit": 90
},
"metrics": [
{
"date": "2025-05-02",
"prints": 2026,
"site_id": "MLA",
"currency": "ARS",
"clicks": 20,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 3000.00,
"cpc": 150.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
],
"summary": {
"prints": 2026,
"clicks": 20,
"site_id": "MLA",
"currency": "ARS",
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 3000.00,
"cpc": 150.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"competitive": {
"lost_impression_share_by_budget": 0.7,
"lost_impression_share_by_ad_rank": 0.04,
"impression_share": 0.26,
"competitive_cpc": 175.0
}
}
}Resposta: Nova (a partir de 04 de Agosto)
{
"dashboard": {
"ctr": [
{
"x": "2025-05-01",
"y": 0.07
},
{
"x": "2025-05-02",
"y": 0.01
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 0.01
}
],
"campaignId": [
{
"x": "2025-05-01",
"y": 0
},
{
"x": "2025-05-02",
"y": 0
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 0
}
],
"acos": [
{
"x": "2025-05-01",
"y": 0.00
},
{
"x": "2025-05-02",
"y": 0.00
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 0.00
}
],
"attribution_order_amount": [
{
"x": "2025-05-01",
"y": 0.00
},
{
"x": "2025-05-02",
"y": 0.00
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 0.00
}
],
"attribution_order_conversions": [
{
"x": "2025-05-01",
"y": 0
},
{
"x": "2025-05-02",
"y": 0
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 0
}
],
"prints": [
{
"x": "2025-05-01",
"y": 362
},
{
"x": "2025-05-02",
"y": 1244
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 2547
}
],
"consumed_budget": [
{
"x": "2025-05-01",
"y": 13523.60
},
{
"x": "2025-05-02",
"y": 10420.76
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 25034.95
}
],
"leads": [
{
"x": "2025-05-01",
"y": 0
},
{
"x": "2025-05-02",
"y": 0
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 0
}
],
"cost_per_clicks": [
{
"x": "2025-05-01",
"y": 520.14
},
{
"x": "2025-05-02",
"y": 744.34
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 641.92
}
],
"clicks": [
{
"x": "2025-05-01",
"y": 26
},
{
"x": "2025-05-02",
"y": 14
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 39
}
],
"keyword": [
{
"x": "2025-05-01",
"y": 0
},
{
"x": "2025-05-02",
"y": 0
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 0
}
],
"cvr": [
{
"x": "2025-05-01",
"y": 0.00
},
{
"x": "2025-05-02",
"y": 0.00
},
{
"x": "2025-05-03",
"y": 0
},
{
"x": "2025-05-04",
"y": 0
},
{
"x": "2025-05-05",
"y": 0.00
}
]
},
"metrics": [
{
"date": "2025-05-01",
"metrics": {
"prints": 362,
"clicks": 26,
"ctr": 0.07,
"cvr": 0.00,
"acos": 0.00,
"attribution_order_conversions": 0,
"attribution_order_amount": 0.00,
"consumed_budget": 13523.60,
"cost_per_clicks": 520.14,
"leads": 0
}
},
{
"date": "2025-05-02",
"metrics": {
"prints": 1244,
"clicks": 14,
"ctr": 0.01,
"cvr": 0.00,
"acos": 0.00,
"attribution_order_conversions": 0,
"attribution_order_amount": 0.00,
"consumed_budget": 10420.76,
"cost_per_clicks": 744.34,
"leads": 0
}
},
{
"date": "2025-05-05",
"metrics": {
"prints": 2547,
"clicks": 39,
"ctr": 0.01,
"cvr": 0.00,
"acos": 0.00,
"attribution_order_conversions": 0,
"attribution_order_amount": 0.00,
"consumed_budget": 25034.95,
"cost_per_clicks": 641.92,
"leads": 0
}
}
],
"summary": {
"prints": 4153,
"clicks": 79,
"ctr": 0.01,
"cvr": 0.00,
"acos": 0.00,
"attribution_order_conversions": 0,
"attribution_order_amount": 0.00,
"consumed_budget": 48979.31,
"cost_per_clicks": 619.99,
"leads": 0,
"competitive_cpc": 200.0,
"impression_share": 0.03,
"lost_impression_share_by_ad_rank": 0.0,
"lost_impression_share_by_budget": 0.97
}
}Métricas de keywords por campanha e dias
Obtém as métricas de palavras-chave de cada dia para uma campanha específica.
Parâmetros obrigatórios
date_from: data desde a consulta em formato YYYY-MM-DD.
date_to: data até a consulta em formato YYYY-MM-DD.
Parâmetros opcionais
limit: por padrão 50.
offset: por padrão 0.
aggregation_type: tipo de agregado de dados a mostrar. Valores possíveis: daily, total. Por defeito retorna ambos.
keywords: palavras-chave específicas para consultar.
strategy: tipo da campanha. Valores possíveis: marketplace ou veículos.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/keywords/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/101010/brand_ads/campaigns/123456/keywords/metrics?date_from=2024-07-01&date_to=2024-07-10Resposta: Atual (até de 04 de Agosto)
{
"paging": {
"total": 1,
"offset": 0,
"limit": 90
},
"metrics": [
{
"date": "2024-07-08",
"keywords": [
{
"keyword": "cloruro magnesio",
"site_id": "MLA",
"currency": "ARS",
"prints": 2,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
]
}
],
"summary": [
{
"keyword": "cloruro magnesio",
"site_id": "MLA",
"currency": "ARS",
"prints": 2,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
]
}Resposta: Nova (a partir de 04 de Agosto)
{
"metrics": [
{
"keyword": "gel",
"prints": 1,
"clicks": 0,
"ctr": 0,
"cvr": 0,
"acos": 0,
"attribution_order_conversions": 0,
"attribution_order_amount": 0.0,
"consumed_budget": 0.0,
"cost_per_clicks": 0,
"leads": 0,
"won_auctions": 0.0,
"recommendation": 0.0,
"is_deleted": false
}
],
"summary": [
{
"keyword": "productos para el cuidado facial",
"prints": 292,
"clicks": 0,
"attribution_order_conversions": 0,
"attribution_order_amount": 0.0,
"consumed_budget": 0.0,
"leads": 0,
"won_auctions": 0.0,
"goal_cpc_max": 0.0,
"is_deleted": false
},
]
}Comparação entre os campos da atual e da nova resposta
Metrics
| Campo atual | Novo campo |
|---|---|
| prints | prints |
| clicks | clicks |
| ctr | ctr |
| cvr | cvr |
| acos | acos |
| consumed_budget | consumed_budget |
| cpc | cost_per_clicks |
| event_time.units_quantity | attribution_order_conversions |
| event_time.units_amount | attribution_order_amount |
| event_time.items_quantity | attribution_order_conversions |
| event_time.ppv_conversions | Removido |
| event_time.bookmark_conversions | Removido |
| event_time.cart_conversions | Removido |
| event_time.checkout_conversions | Removido |
| event_time.leads_question_conversions | leads |
| event_time.leads_im_conversions | leads |
| event_time.eshop_conversions | Removido |
| touch_point.units_quantity | attribution_order_conversions |
| touch_point.units_amount | attribution_order_amount |
| touch_point.items_quantity | attribution_order_conversions |
| touch_point.ppv_conversions | Removido |
| touch_point.bookmark_conversions | Removido |
| touch_point.cart_conversions | Removido |
| touch_point.checkout_conversions | Removido |
| touch_point.leads_question_conversions | leads |
| touch_point.leads_im_conversions | leads |
| touch_point.eshop_conversions | Removido |
| - | won_auctions |
| - | goal_cpc_max |
Summary
| Campo atual | Novo campo |
|---|---|
| prints | prints |
| clicks | clicks |
| ctr | ctr |
| cvr | cvr |
| acos | acos |
| consumed_budget | consumed_budget |
| cpc | cost_per_clicks |
| event_time.units_quantity | attribution_order_conversions |
| event_time.units_amount | attribution_order_amount |
| event_time.items_quantity | attribution_order_conversions |
| event_time.ppv_conversions | Removido |
| event_time.bookmark_conversions | Removido |
| event_time.cart_conversions | Removido |
| event_time.checkout_conversions | Removido |
| event_time.leads_question_conversions | leads |
| event_time.leads_im_conversions | leads |
| event_time.eshop_conversions | Removido |
| touch_point.units_quantity | attribution_order_conversions |
| touch_point.units_amount | attribution_order_amount |
| touch_point.items_quantity | attribution_order_conversions |
| touch_point.ppv_conversions | Removido |
| touch_point.bookmark_conversions | Removido |
| touch_point.cart_conversions | Removido |
| touch_point.checkout_conversions | Removido |
| touch_point.leads_question_conversions | leads |
| touch_point.leads_im_conversions | leads |
| touch_point.eshop_conversions | Removido |
| - | won_auctions |
| - | goal_cpc_max |
| competitive_cpc | competitive_cpc |
| impression_share | impression_share |
| lost_impression_share_by_ad_rank | lost_impression_share_by_ad_rank |
| lost_impression_share_by_budget | lost_impression_share_by_budget |
Métricas de Campanhas por Período (Novo - a partir de 04/08/25)
Com esta nova consulta é possível obter as métricas de todas as campanhas de um advertiser para um período de tempo determinado.
Parâmetros obrigatórios
date_from: data desde a consulta em formato YYYY-MM-DD.
date_to: data até a consulta em formato YYYY-MM-DD.
Parâmetros opcionais
limit: por padrão 50.(não é possível alterar)
offset: por padrão 0.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/full_summary?date_from=YYYY-MM-DD&date_to=YYYY-MM-DDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/101010/brand_ads/campaigns/full_summary?date_from=2024-07-01&date_to=2024-07-10Resposta:
{
"summary": [
{
"campaignId": 12445,
"name": "AVIT",
"type": "Personalizada",
"status": "ACTIVE",
"reason_status": "BLOCKED",
"startDate": "2025-02-13",
"endDate": null,
"budget": 350.00,
"destinationId": 456,
"goal_value": 0.33,
"campaign_tags": null,
"site_id": "MLB",
"currency": "BRL",
"official_store_id": 123,
"eshop_id": null,
"metrics": {
"prints": 49508,
"clicks": 262,
"ctr": 0.00,
"cvr": 0.01,
"acos": 284.50,
"attribution_order_conversions": 5,
"attribution_order_amount": 156965.00,
"consumed_budget": 446563.77,
"cost_per_clicks": 1704.44,
"leads": 0
}
}
],
"pagination": {
"total_elements": 1,
"total_pages": 1,
"offset": 1,
"limit": 50
}
}Campos da resposta
campaignId: id da campanha
name: nome da campanha
type:tipo da campanha - valores possíveis: CUSTOM ou AUTOMATIC
status:status da campanha - valores possíveis: ACTIVE, PAUSED ou BLOCKED
startDate:início da campanha
endDate:fim da campanha
budget:orçamento da campanha
goal_value:valor máximo permitido para o custo por clique (CPC) de uma campanha
site_id:site da campanha
official_store_id: loja oficial do item associado
Possíveis erros ao consultar as métricas
Códigos de estado de resposta:
- 204 - No content: Nenhuma métrica encontrada para o advertiser. A resposta será vazia.
{} - 400 - Bad request: Campo obrigatório não é enviado, range de datas acima de 90 dias ou campo obrigatório é enviado com valor incorreto.
{ "description": "Validation Error", "cause": [ { "error 1": "Parameter date_to is required" } ], "error": "bad_request", "status": 400 } - 401 - Unauthorized: Usuário não tem a permissão de verificar as métricas/informações do advertiser.
{ "description": "Unauthorized access", "cause": [ { "cause": "User unauthorized" } ], "error": "unauthorized", "status": 401 } - 500 - Internal Server Error: O servidor encontrou um erro inesperado e não conseguiu completar a requisição.
{ "description": "The server has an unexpected error and cannot complete the request", "error": "internal_server_error", "status": 500 }
Glossário
prints (impressões): é a quantidade de vezes que os seus anúncios foram exibidos.
clicks: quantidade de vezes que os usuários clicaram nos seus anúncios.
ctr (click-through rate): taxa de cliques obtidos sobre o total de impressões.
cvr (conversion rate): taxa de conversão em relação aos cliques.
consumed_budget (investimento): quantidade de dinheiro efetivamente gasto para exibir seus anúncios.
cpc (custo por clique): custo médio pago por cada clique que os anúncios receberam.
acos (advertising cost of sales): investimento/receita, custo publicitário das vendas.
attribution_order_amount (receita): valor total gerado pelas vendas atribuídas aos seus anúncios.
attribution_order_conversions : quantidade de itens vendidos por atribuições.
leads : quantidade de potenciais clientes interessados em adquirir o seu produto que perguntaram ou que entraram em contato pelo WhatsApp a partir da sua publicação após clicar nos seus anúncios.
As métricas de competitividade são mostradas apenas no nível de campanha e refletem sua distribuição de impressões, ou seja, são porcentagens relacionadas ao número de vezes que seus anúncios patrocinados foram mostrados ou não em relação a 100% das vezes em que poderiam ter sido mostrados. São calculadas com os dados dos últimos 7 dias. As métricas podem ser:
- lost_impression_share_by_budget (Perdidas por orçamento): percentual de perda, entendendo como tal as impressões potenciais que não puderam ser capitalizadas por orçamento baixo. Por exemplo: se for 10, significa que a campanha perdeu impressões em 10% das vezes em que poderia tê-las, por não ter orçamento suficiente. Nestes casos, recomendamos aumentar o orçamento.
- lost_impression_share_by_ad_rank (Perdidas por ranking): percentual de perda, entendendo como tal as impressões potenciais que não puderam ser capitalizadas por ranking baixo. Por exemplo, se o resultado for 30, a campanha perdeu impressões em 30% das vezes em que poderia tê-las, por não ter ad-rank suficiente.
O adrank é composto pelo Acos Target e pelo Quality Score (métrica interna, não é gerenciável diretamente). Para melhorar as impressões ganhas por ranking, sugerimos focar nas seguintes ações:
Revisar o CPC máximo: o recomendável é que você esteja dentro da média de sua concorrência para melhores resultados.
Verificar se a campanha está segmentada nas palavras-chave corretas: recomendamos ter diferentes campanhas para focar em palavras-chave específicas em cada uma.
Melhorar a qualidade da publicação: a qualidade das fotos, a descrição do seu produto e até as condições de envio podem influenciar seu ranking.
Cuidar da reputação: o serviço pós-venda e a avaliação do produto podem fazer a diferença na concorrência. Saiba mais sobre a API de Qualidade de Publicações.
- impression_share (Impressões ganhas): percentual de sucesso, entendendo como tal as impressões efetivas, ou seja, o percentual de vezes que a campanha ganhou os leilões em que participou com aquela palavra-chave. É a quantidade de impressões obtidas dividida pela quantidade de impressões estimadas/potenciais que poderia ter tido. Por exemplo: se for 60%, significa que a campanha ganhou e foi exibida em 60% das vezes em que poderia ter sido.
- competitive_cpc: é o CPC da concorrência.
Seguinte: Display Ads.