Real-Time Delivery Performance API
Real Time Ad Delivery Metrics
Fetch near real-time delivery data for campaigns or ad groups, including impressions, clicks, and ad spend-either lifetime (total) or for today only (today)
Notes
- Metrics are refreshed every ~15 minutes
- To track hourly changes, poll this API at fixed intervals
GET /api/v1/stats
Query Parameters
| Parameter | Description | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | The ID of the specific advertiser | integer | Y | A valid advertiser ID |
| 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 adgroup 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 | string | N |
(default: total) |
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 for all matching campaignId or adgroupId specified in the list
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 |
| WM_CONSUMER.ID | 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 | Auth signature as an API key. | Y | Use the signature generator code from Getting Started Guide to generate this value |
| WM_SEC.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/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 stats were 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 | integer |
| campaigns | Array containing campaign metrics where each object represents a campaign The campaigns objects are detailed | array |
| adGroups | Array containing ad group level metrics where each object represents an ad group The adGroups objects are detailed | array |
campaigns Objects
campaigns object is included in the response only if campaignIds are specified in the request
| Element | Description | Type |
|---|---|---|
| campaignId | ID of the campaign | Integer |
| metrics | It contains today and total metric objects Find more info on metrics object | json |
adGroups Objects
adGroups 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 | It contains today and total metric objects Find more info on metrics object | json |
metrics Objects
| Element | Description | Type |
|---|---|---|
| total | Aggregated metrics (impressions, clicks and ad spend) since the start of the adgroup. This object will be preset when timeWindow = total or all Find more info on total or today object | json |
| today | Aggregated metrics (impressions, clicks and ad spend) for current day only. This object will be preset when timeWindow = today or all Find more info on total or today object | json |
total/today objects
| Element | Description | Type |
|---|---|---|
| impressions | Total number of ad views | Integer |
| clicks | Total number of clicks | Integer |
| adSpend | Total adspend | Float |
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 }, "today": { "impressions": 4300, "clicks": 105, "adSpend": 22.8 } } }, { "campaignId": 2, "metrics": { "total": { "impressions": 94000, "clicks": 1980, "adSpend": 412.1 }, "today": { "impressions": 1900, "clicks": 50, "adSpend": 9.95 } } } ], "adGroups": [ { "adGroupId": 101, "campaignId": 1, "metrics": { "total": { "impressions": 120000, "clicks": 3200, "adSpend": 645.75 }, "today": { "impressions": 2500, "clicks": 60, "adSpend": 12.5 } } }, { "adGroupId": 102, "campaignId": 1, "metrics": { "total": { "impressions": 87000, "clicks": 2100, "adSpend": 483.2 }, "today": { "impressions": 1800, "clicks": 45, "adSpend": 10.3 } } }, { "adGroupId": 104, "campaignId": 1, "metrics": { "total": { "impressions": 94000, "clicks": 1980, "adSpend": 412.1 }, "today": { "impressions": 1900, "clicks": 50, "adSpend": 9.95 } } } ]
}
Sample Response-Failure
Error Code - 400
[ { "code": "failure", "details": [ "BOTH_CAMPAIGNS_AND_ADGROUPS_LIST_CAN_NOT_BE_NULL" ] } ]
Updated 1 day ago