Read the metric series of one ad campaign
const url = 'https://open-api.live.gobots.com.br/v1/ads/meli/campaigns/example/metrics?start_date=2026-09-01&end_date=2026-09-30&timezone=America%2FSao_Paulo&granularity=week';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://open-api.live.gobots.com.br/v1/ads/meli/campaigns/example/metrics?start_date=2026-09-01&end_date=2026-09-30&timezone=America%2FSao_Paulo&granularity=week' \ --header 'Authorization: Bearer <token>'Spend, impressions, clicks, attributed sales and the ratios derived from them, per day, ISO
week, calendar month or as one total, read live from the marketplace, for the one store the
campaign belongs to. Days are cut in that store’s site zone (data.timezone) and money is in
its site currency (data.currency), for every Mercado Livre site; the window reaches at most
90 days back. Today is partial until the marketplace refreshes (Mercado Livre documents 10:00
GMT-3, not confirmed for sites other than Brazil): a window that includes the store’s today
answers complete: false with the warning ads_metrics_today_partial. Responses are cached
for 5 minutes per query.
Authorizations
Seção intitulada “Authorizations”Parameters
Seção intitulada “Parameters”Path Parameters
Seção intitulada “Path Parameters”Marketplace of the Ads account. Only meli has an adapter in v1; the others answer 501.
The marketplace’s own campaign id. An id outside the charset answers 404.
Header Parameters
Seção intitulada “Header Parameters”The ETag of a previously fetched representation; a match answers 304 with no body.
Query Parameters
Seção intitulada “Query Parameters”First day of the window, inclusive, at most 90 days before today.
Example
2026-09-01Last day of the window, inclusive. At most 90 days of range, never in the future.
Example
2026-09-30Defaults to each store’s site zone, the only zone its days exist in. When given, it must equal the zone of every store in the answer; otherwise the request answers 400.
Example
America/Sao_PauloBucket size. Defaults to day. total answers the totals and an empty series.
Example
weekResponses
Seção intitulada “Responses”The series of the campaign.
object
The campaign’s store, as in AdsStoreMetrics, plus the campaign id and the window.
object
Opaque store id.
ok: read. no_ads_account: the store has no Ads account on its site, or the site has no
Product Ads; zeros are a true answer and carry no warning. unavailable: could not be read.
ISO 4217 code of the store’s site; every amount of this object is in it. Null only on an
unavailable store the marketplace did not name it for.
IANA zone the store’s days are cut in. Null only on an unavailable store the
marketplace did not name it for.
False when a warning of this store says part of its window is missing or not final.
A campaign’s current metric snapshot, or one bucket of a metric series. Ratios are decimal
strings. A metric the origin did not send is absent, never zero. In a series every ratio is
re-derived from the bucket’s sums (4 decimals, money 2) and is absent when its denominator is
zero; share_of_voice is present on day buckets only.
object
object
Decimal string.
ISO 4217, uppercase.
object
Decimal string.
ISO 4217, uppercase.
object
Decimal string.
ISO 4217, uppercase.
Marketplace-specific fields, keyed by marketplace and then by a documented key. Campaign:
channel. Campaign metrics: share_of_voice (decimal string, a ratio in [0,1]). Ad group: status (the
marketplace’s own), ad_group_type. Opportunity: action (an action outside the published set).
object
object
Every bucket of the window in order, days without activity included; empty for total.
totals and series are absent when the store is unavailable.
One bucket, clipped to the window; a week starts on Monday.
object
A campaign’s current metric snapshot, or one bucket of a metric series. Ratios are decimal
strings. A metric the origin did not send is absent, never zero. In a series every ratio is
re-derived from the bucket’s sums (4 decimals, money 2) and is absent when its denominator is
zero; share_of_voice is present on day buckets only.
object
object
Decimal string.
ISO 4217, uppercase.
object
Decimal string.
ISO 4217, uppercase.
object
Decimal string.
ISO 4217, uppercase.
Marketplace-specific fields, keyed by marketplace and then by a documented key. Campaign:
channel. Campaign metrics: share_of_voice (decimal string, a ratio in [0,1]). Ad group: status (the
marketplace’s own), ad_group_type. Opportunity: action (an action outside the published set).
object
object
object
object
True when every store is complete and no other warning says part of the window is missing
or not final; ads_currency_mixed_timezones alone leaves it true.
Distinct union of the warnings of every store and currency entry: ads_metrics_today_partial,
ads_store_unavailable, ads_source_partial, ads_unmapped_row_skipped,
unmapped_store_skipped, ads_currency_mixed_timezones.
Example
{ "data": { "status": "ok", "currency": "ARS", "timezone": "America/Argentina/Buenos_Aires", "warnings": [ "ads_metrics_today_partial" ], "totals": { "spend": { "amount": "250.0" }, "cpc": { "amount": "250.0" }, "attributed_sales": { "amount": "250.0" } }, "series": [ { "metrics": { "spend": { "amount": "250.0" }, "cpc": { "amount": "250.0" }, "attributed_sales": { "amount": "250.0" } } } ], "period": { "granularity": "day" } }, "meta": { "dictionary_version": "1.0.0", "warnings": [ "ads_metrics_today_partial" ] }}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
Strong validator of the representation.
The representation is unchanged. The request still counts as one request.
Headers
Seção intitulada “Headers”Strong validator of the representation.
The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
The marketplace or a query parameter carries a value the contract does not accept
(invalid_request), the period exceeds the maximum (period_too_long), or the cursor is
expired or was not issued for this query (invalid_cursor).
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
The API key is missing, malformed, unknown, revoked or expired.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”Bearer challenge for the API realm.
The merchant does not have the Open API add-on active.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}The resource, or a requested store, is not this merchant’s or does not exist; the two are indistinguishable.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
The requests-per-minute limit of the endpoint group was exceeded (rate_limited), or the
monthly request quota of the merchant is exhausted (quota_exceeded).
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
Seconds to wait before retrying, per RFC 9110.
The route or marketplace is published but its adapter is not available yet.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
The upstream source is unavailable. When the merchant’s entitlement could not be resolved the request is refused before rate limiting, so the RateLimit headers are absent.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”As the RateLimit-Policy response header; absent when entitlement could not be resolved.
As the RateLimit response header; absent when entitlement could not be resolved.