Overview

Retrieve near real-time delivery, budget, and pacing metrics for Onsite Display campaigns and ad groups.

Use the Stats API to monitor in-flight performance, track budget utilization, power operational dashboards, and support automated optimization workflows.

Metrics refresh approximately every 15 minutes, providing current delivery visibility without waiting for daily reporting.

Availability

Supported for self-serve Onsite Display campaigns.

How it works

The Stats API returns delivery metrics directly in the API response. Unlike Snapshot Reporting, it does not require an asynchronous job or file download.

Before you begin

• Valid advertiserId with reporting access
• At least one valid campaign ID or ad group ID
• Determine whether campaign-level, ad group-level, or both sets of metrics are needed
• Select the appropriate reporting time window

Endpoint

GET /api/v1/stats

View technical specifications

Request details

How this request is used

Use this endpoint to retrieve current delivery metrics for one or more campaigns or ad groups.

Campaign and ad group IDs can be requested independently or together.

Key fields and behaviors

• campaignIds
  Optional when adGroupIds is supplied. Retrieves campaign-level metrics for up to 50 campaign IDs per request.
• adGroupIds
  Optional when campaignIds is supplied. Retrieves ad group-level metrics for up to 50 ad group IDs per request.
• timeWindow
  Controls whether the response returns current-day metrics, lifetime metrics, or both. Supported values: today, total, all.

Entity selection rules

• Include at least one campaignIds or adGroupIds value.
• Campaign IDs and ad group IDs are independent filters.
• Both parameters can be included in the same request.
• Each parameter supports up to 50 IDs.
• IDs must belong to the specified advertiser.

Configure timeWindow

Use timeWindow to select the reporting period that best supports your monitoring workflow.

For example, use timeWindow=all when your platform needs to display both current-day spend and lifetime spend together.

Data freshness

Stats metrics refresh approximately every 15 minutes.

The response includes timestamps that help partners distinguish when the response was generated from when the underlying metrics were last refreshed.

• asOf
  Timestamp indicating when the response was generated
• lastUpdatedAt
  Timestamp indicating when the underlying delivery metrics were last refreshed

These timestamps may differ because the API can return the most recently available metrics between refresh cycles.

Sample request

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: <auth_signature>' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: <consumer_id>' \ --header 'WM_CONSUMER.intimestamp: <timestamp>'

This example retrieves both current-day and lifetime metrics for two campaigns and three ad groups.

Response details

What this response returns

The API returns delivery and budget metrics for the requested campaigns and ad groups.

Results are organized by entity level and requested time window.

• campaigns contains campaign-level results when campaign IDs are requested.
• adGroups contains ad group-level results when ad group IDs are requested.
• Metrics correspond to today, total, or both, depending on the requested timeWindow.

Key fields to use

• asOf
  Timestamp when the response was generated
• lastUpdatedAt
  Timestamp when the delivery metrics were last refreshed.
• campaigns
  Campaign-level results.
• adGroups
  Ad group-level results

Delivery metrics

• impressions
  Number of ad impressions recorded during the selected time window
• clicks
  Number of ad clicks recorded during the selected time window
• adSpend
  Estimated advertising spend during the selected time window
• validBids
  Number of valid bids recorded during the selected time window

Budget and pacing metrics

• limit
  Configured budget limit
• remaining
  Budget remaining
• outOfBudgetAt
  timestamp when the budget was exhausted, when applicable
• sourceLevel
  Indicates whether the budget is configured at the campaign or ad group level (campaign, ad_group)
• pacingPercent
  Percentage of budget spent

Interpreting delivery and budget metrics

Delivery monitoring

Use impressions, clicks, adSpend, and validBids to understand whether campaigns or ad groups are delivering.

For current-day monitoring, use timeWindow=today.

For cumulative delivery analysis, use timeWindow=total.

Budget utilization

Use limit, remaining, and pacingPercent to monitor budget consumption.

The sourceLevel field identifies where the budget is configured, helping partners interpret budget metrics when campaign and ad group configurations differ.

If outOfBudgetAt is returned, use it to identify when the applicable budget was exhausted.

Data freshness

Use lastUpdatedAt to determine how recently the metrics were refreshed. Timestamps are normalized to eastern time.

Because data refreshes approximately every 15 minutes, values may not reflect activity occurring immediately before the request.

Sample response

The response includes campaign and ad group result collections along with the reporting timestamps.

The following excerpt illustrates the top-level response fields.

{ "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": 101.00 } }, { "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" }, "pacing": { "sourceLevel": "AD_GROUP" } } ], "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": "CAMPAIGN" }, "pacing": { "sourceLevel": "CAMPAIGN" } }, { "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": 2, "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 } }, "pacing": { "sourceLevel": "AD_GROUP", "pacingPercent": 0.10 } }, { "adGroupId": 105, "campaignId": 2, "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": "TOTAL", "total":{ "limit": 1000.0, "remaining": 900.0 } }, "pacing": { "sourceLevel": "AD_GROUP", "pacingPercent": 0.10 } } ]
}

Reporting limitations

The Stats API provides delivery and budget metrics at the campaign and ad group levels.

It does not provide:

• Sales or retail performance data
• Attribution reporting
• Creative-level reporting
• SKU-level reporting

Use Snapshot Reporting for historical performance, attribution, and other report-specific metrics.

Best practices

Align monitoring workflows with the approximately 15-minute data refresh cadence.

• Use lastUpdatedAt to evaluate metric freshness.
• Use today for intraday pacing and total for cumulative delivery.
• Use all when both time windows are needed in the same workflow.
• Avoid treating estimated delivery metrics as finalized reporting.

Common issues

• Omitting both campaignIds and adGroupIds
• Requesting more than 50 campaign IDs or 50 ad group IDs
• Using IDs that do not belong to the specified advertiser
• Selecting the wrong timeWindow for the monitoring use case
• Treating estimated spend as finalized spend
• Assuming metrics update continuously rather than approximately every 15 minutes
• Expecting attribution, sales, creative, or SKU metrics in the response
• Attempting to retrieve data for unsupported Managed service or offsite advertisers

What happens next

After retrieving Stats metrics:

1. Review the response timestamps to confirm data freshness.
2. Evaluate current-day or cumulative delivery against monitoring targets.
3. Use the results to support pacing dashboards, alerts, or optimization workflows.
4. Retrieve finalized historical metrics through Performance Snapshot Reporting when needed.

Related pages

• Reporting API Overview
• Snapshot Reporting
• Performance Snapshot Reports
• Latest Report Date
• Dimensions and Metrics