Fetch near real-time delivery, budget utilization, and pacing metrics for display campaigns or ad groups belonging to self-serve advertiser accounts. This includes delivery metrics (impressions, clicks, adSpend, validBids), remaining budget, and pacing percent. Delivery metrics can be returned for lifetime (total), today (today), or both (all), and are refreshed approximately every 15 minutes. To track hourly changes, poll this API at fixed intervals.

Notes:

Repeated polling within a short interval may return identical results.
All timestamps are normalized to Eastern Time (ET)

📘
URL: GET /api/v1/stats

Query Parameters

Parameter	Description	Type	Required	Possible Values
`advertiserId`	Unique identifier of the advertiser whose campaign or ad group metrics are being requested.	Integer	Y	Integer
`campaignIds`	List of campaign IDs for which the metrics are to be retrieved. Note: Required if `adGroupIds` is not provided.	Array[Integer]	Conditional	Up to 50 campaign IDs
`adGroupIds`	List of ad group IDs for which the metrics are to be retrieved. Note: Required if `campaignIds` is not provided.	Array[Integer]	Conditional	Up to 50 ad group IDs
`timeWindow`	Specifies the time window for which the metrics are to be returned. `today`: metrics for the current day, as of the time requested. `total`: metrics for the lifetime of the campaign or ad group, as of the time requested. `all`: returns metrics for both the current day and lifetime. Note: This parameter affects only the contents of the `metrics` object in the response.	String	N	`today`, `total`, or `all` (default: `total`)

Notes

You must pass at least one of: campaignIds or adGroupIds. Both cannot be null.
campaignIds and adGroupIds are independent filters. Return data matching all specified campaignId or adGroupId values.
timeWindow affects only the contents of the metrics object.

Notes:

You must pass at least one of: campaignIds OR adGroupIds. Both cannot be null. A 400 error will be returned otherwise
campaignIds and adGroupIds are independent filters. Return data matching all matching campaignId or adGroupId values specified in the list
timeWindow affects only the contents of the metrics object

Headers

Header Name	Description	Required	Values
Authorization	The token will provide you the access to the API. It is same for all advertisers you access through the API.	Y	Please utilize the generated `auth_token` shared with you at the time of partner onboarding from the Getting Started Guide
Content-Type	Format of the message body	Y	application/json
WM_CONSUMER.ID	Unique ID for consumer. We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.	Y	Please use the generated `ConsumerId` shared with you at the time of partner onboarding. Refer to the Getting Started Guide for more information
WM_SEC.AUTH_SIGNATURE	Signature for authentication	Y	Use the signature generator code from Getting Started Guide to generate this value
WM_SEC.KEY_VERSION	Key version. We will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API.	Y	1
WM_CONSUMER.intimestamp	Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp.	Y	Use the signature generator code from Getting Started Guide to generate this value

Sample Request-Success

curl -X GET \ 'https://developer.api.us.walmart.com/api-proxy/service/display/api/v1/stats?advertiserId=1000&campaignIds=1,2&adGroupIds=101,102,104&timeWindow=all' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779'

Response

Element	Description	Type
advertiserId	ID of the advertiser	Integer
asOf	Timestamp when metrics snapshot was generated (ISO 8601). Possible values: timestamp in ISO8601 format normalized to ET	String
lastUpdatedAt	Timestamp when metrics were last refreshed (ISO 8601). Possible values: timestamp in ISO8601 format normalized to ET	String
campaigns	Array containing campaign metrics where each object represents a campaign. Included in the response only if `campaignIds` are specified in the request.	array
adGroups	Array containing ad group level metrics where each object represents an ad group. Included in the response only if `adGroupIds` are specified in the request.	array

campaigns Objects

This object is included in the response only if campaignIds are specified in the request.

Element	Description	Type
campaignId	ID of the campaign	Integer
metrics	Contains aggregated delivery metrics for the specified time window. `total` is included when `timeWindow=total` or `all`. `today` is included when `timeWindow=today` or `all`.	object
budget	Budget details of the campaign, if budget is set at ad group level	object
pacing	Pacing details of the campaign, if budget is set at ad group level	object

adGroups Objects

This object is included in the response only if adGroupIds are specified in the request.

Element	Description	Type
adGroupId	ID of the ad group	Integer
campaignId	ID of the campaign	Integer
metrics	Contains today and total metric objects	object
budget	Budget details of the ad group, if budget is set at ad group level	object
pacing	Pacing details of the ad group, if budget is set at ad group level	object

metrics Objects

Element	Description	Type
total	Aggregated metrics including impressions, clicks, ad spend, and valid bids since the start of the campaign or ad group. Present when `timeWindow=total` or `all`.	object
today	Aggregated metrics including impressions, clicks, ad spend, and valid bids for the current day only. Present when `timeWindow=today` or `all`.	object

today/total Objects

Element	Description	Type
impressions	Total number of ad views	Integer
clicks	Total number of clicks	Integer
adSpend	Total ad spend	Float
validBids	Total number of valid bids	Integer

budget Objects

Contains budget configuration for the campaign or ad group, based on where the budget is defined.

Element	Description	Type	Possible Values
sourceLevel	Source level at which the budget is set	String	`CAMPAIGN`, `AD_GROUP`
budgetType	Indicates whether the budget is defined per day (`DAILY`) or for the full lifetime (`TOTAL`)	String	`DAILY`, `TOTAL`
total	Budget details when budget is set for the lifetime. Present when `budgetType=TOTAL`	object
daily	Budget details when budget is set for a day. Present when `budgetType=DAILY`	object

budget.total / budget.daily Objects

Element	Description	Type
limit	Budget limit	Float
remaining	Budget remaining	Float
outOfBudgetAt	Timestamp indicating when the budget was exhausted. Returns `null` if the budget has not yet been exhausted. Timestamp is normalized to ET.	String

pacing Objects

Element	Description	Type	Possible Values
sourceLevel	Source level at which the budget is set	String	`CAMPAIGN`, `AD_GROUP`
pacingPercent	Fraction of the allocated budget that has been utilized, expressed as a value between 0.00 and 1.00	Float	`0.00` to `1.00`

Sample Response - Success

{ "asOf": "2025-04-15T10:00:00.000-04:00", "lastUpdatedAt": "2025-04-15T09:30:00.000-04:00", "advertiserId": 1000, "campaigns": [ { "campaignId": 1, "metrics": { "total": { "impressions": 207000, "clicks": 5300, "adSpend": 1128.95, "validBids": 0 }, "today": { "impressions": 4300, "clicks": 105, "adSpend": 22.8, "validBids": 0 } }, "budget": { "sourceLevel": "CAMPAIGN", "budgetType": "TOTAL", "total": { "limit": 10000.0, "remaining": 0.0, "outOfBudgetAt": "2025-03-27T13:22:000-05:00" } }, "pacing": { "sourceLevel": "CAMPAIGN", "pacingPercent": 0.25 } }, { "campaignId": 2, "metrics": { "total": { "impressions": 94000, "clicks": 1980, "adSpend": 412.1, "validBids": 100 }, "today": { "impressions": 1900, "clicks": 50, "adSpend": 9.95, "validBids": 12 } }, "budget": { "sourceLevel": "AD_GROUP", "budgetType": "DAILY", "daily": { "limit": 1000.0, "remaining": 900.0, "outOfBudgetAt": null } }, "pacing": { "sourceLevel": "AD_GROUP", "pacingPercent": 0.25 } } ], "adGroups": [ { "adGroupId": 101, "campaignId": 1, "metrics": { "total": { "impressions": 120000, "clicks": 3200, "adSpend": 645.75, "validBids": 0 }, "today": { "impressions": 2500, "clicks": 60, "adSpend": 12.5, "validBids": 0 } }, "budget": { "sourceLevel": "AD_GROUP" }, "pacing": { "sourceLevel": "AD_GROUP" } }, { "adGroupId": 102, "campaignId": 1, "metrics": { "total": { "impressions": 87000, "clicks": 2100, "adSpend": 483.2, "validBids": 0 }, "today": { "impressions": 1800, "clicks": 45, "adSpend": 10.3, "validBids": 0 } }, "budget": { "sourceLevel": "CAMPAIGN" }, "pacing": { "sourceLevel": "CAMPAIGN" } }, { "adGroupId": 104, "campaignId": 1, "metrics": { "total": { "impressions": 94000, "clicks": 1980, "adSpend": 412.1, "validBids": 10 }, "today": { "impressions": 1900, "clicks": 50, "adSpend": 9.95, "validBids": 2 } }, "budget": { "sourceLevel": "AD_GROUP", "budgetType": "DAILY", "daily": { "limit": 1000.0, "remaining": 900.0, "outOfBudgetAt": null } }, "pacing": { "sourceLevel": "AD_GROUP", "pacingPercent": 0.25 } } ]
}