Retrieve today’s near-real time metrics and campaign cap-out insights
Description: You can retrieve following metrics at advertiser/campaign level in near real-time for the time elapsed on the day of request:
- Ad Spend
- Clicks
- Impressions
- Daily Remaining Budget
- Daily Out of budget Date Time
URL: GET /api/v1/stats
Note:
- We recommend that you do not request near real-time statistics more than once per thirty minutes as the refreshed metrics may not reflect before that
- The Ads exposed attribution (Attributed Units Sold, Attributed Revenue) is not part of near real-time metrics. Only the Ads performance metrics (Ad Spend, Clicks, Impressions) are provided in near real-time metrics.
- Campaign budget type vs Daily remaining budget values:
- For Campaigns that have only daily budget defined – then Daily Remaining Budget (Computed Value)
- For Campaigns that have both total and daily budget defined – then Daily Remaining Budget (Computed Value)
- For Campaigns that have only Total Budget defined – then Daily Remaining Budget is NULL
Query Parameters
| Parameter | Description | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | The ID of the advertiser whose performance metrics for today is to be retrieved | integer | Y | Unique numeric identifier |
| campaignId | The ID of the campaign for which the performance metrics for today needs to be retrieved | integer | N | Unique numeric identifier |
Headers
| Header Name | Description | Required | Values |
|---|---|---|---|
| Authorization | The token will provide you the access to the API. It is the 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 further explanation on this |
| 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 (Getting Started Guide) to generate this value |
Sample Request
curl -X GET\ 'https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/stats?advertiserId=600002&campaignId=500001' \ --header 'accept: 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 |
|---|---|---|
| campaignId | Id of the advertising campaign whose ad spend is being retrieved | integer |
| todayAdSpend | The amount of budget spent for current date | double |
| asOf | The asOf field represents the date and time when the returned statistics (including ad spend, impressions, clicks, and daily remaining budget) were generated. Note: 1. The time zone is in PST and time stamp format is 24-hour format. 2. Please review the "asOf" timestamp to confirm when the data was generated and determine if there’s any delay. | string |
| adGroupId | Id of the ad group Note: Please ignore this parameter because we now provide stats at campaign level only, and eventually adGroupId will be removed from the response. For now, we will return ‘-1’ for this field. | integer |
| dailyOutOfBudgetDatetime | An indicator of whether a campaign has yet run out of its assigned daily budget or not. It returns following values: 1. Actual Date and Time: It returns date and timestamp of when the campaign exhausted its daily budget and stopped serving ads. 2. Empty: It returns a blank if the daily budget is not yet exhausted Note: 1. Since it measures spend of daily budget, it only provides date and time stamp for the current day. Also, since it refreshes every day, it will return a blank the subsequent day if the daily budget is not exhausted 2. The time zone is in PST and time stamp format is 24-hour format | string |
| dailyRemainingBudget | The amount of daily budget left after today’s ad spend is consumed | double |
| todayImpressions | Total number of impressions counted for today | integer |
| todayClicks | Total number of clicks counted for today | integer |
Sample Response 1
[ { "campaignId": 500001, "todayAdSpend":777.0, "asOf": "2021-07-29 18:44", "adGroupId": -1, "dailyOutOfBudgetDatetime": "2021-07-29 15:41", "dailyRemainingBudget": 17.2, "todayImpressions": 32421, "todayClicks": 14 }
]
Sample Response 2
Following campaigns’ daily budget is 500 and todayAdSpend is also 500, so dailyRemainingBudget is 0:
[ { "campaignId": 1694255, "adgroupId": -1, "todayAdSpend": 500.0, "asOf": "2022-04-12 20:14", "dailyOutOfBudgetDatetime": "2022-04-12 09:08", "dailyRemainingBudget": 0.0, "todayImpressions": 495627, "todayClicks": 1214 }
]
Sample Response 3
Following campaign has Total Budget defined and Daily Budget is undefined (i.e., Campaign Budget Type: Total). Hence the the Daily Remaining Budget is NULL.
[ { "campaignId": 531760, "adgroupId": -1, "todayAdSpend": 52.0, "asOf": "2022-04-14 15:18", "dailyOutOfBudgetDatetime": null, "dailyRemainingBudget": null, "todayImpressions": 220, "todayClicks": 52 }
]
Updated 3 days ago