List ad groups
Retrieve and review ad group configurations, lifecycle status, and delivery settings.
Overview
Retrieve ad groups within a specific campaign to review their current configuration and lifecycle state.
Use the List Ad Groups API to:
- Synchronize ad group data into partner platforms
- Populate campaign management interfaces
- Review current delivery configuration
- Prepare ad group updates
- Troubleshoot delivery and configuration issues
Read-only endpointThis endpoint retrieves ad group configuration but does not create, update, pause, resume, archive, or delete ad groups.
Availability
Supported for Onsite Display only.
How it works
The List Ad Groups API returns the current configuration of ad groups within a campaign, including lifecycle status, targeting, bidding, budget, schedule, and delivery settings.
Use the returned configuration as the current source of truth before performing downstream management actions such as updating an ad group or changing its delivery status.
Retrieving ad groups is often the first step in validating delivery readiness.
Ad Group
Retrieve delivery configuration.
Lifecycle State
Confirm delivery eligibility.
Targeting
Validate audience and geotargeting setup.
Budget & Schedule
Review delivery controls.
Delivery Ready
Determine whether additional validation is needed.
Common use cases
Delivery Validation
Review ad group delivery settings before launch.
Troubleshooting
Investigate delivery, pacing, or targeting issues.
Platform Synchronization
Keep partner systems aligned with Walmart Connect.
Update Preparation
Retrieve current configuration before submitting updates.
Before you begin
- Valid
advertiserId - Valid
campaignId
Endpoint
POST /api/v1/adGroups/list
POST /api/v1/adGroups/listRequest details
How this request is used
Retrieves ad groups for a specific campaign so you can validate delivery configuration, populate interfaces, troubleshoot issues, or synchronize metadata.
Key fields and behaviors
Filtering behavior
| Filter Used | Result |
|---|---|
| No Filter | All ad groups in the campaign |
adGroupId | Specific ad groups (max 25 IDs) |
name | Exact ad group name |
status | Ad groups in a specified lifecycle state |
lastModifiedDate | Ad groups created or updated on or after the specified date |
Supported lifecycle states
draftscheduledlivepausedcompletedarchived
Pagination
| Parameter | Description |
|---|---|
startIndex | starting index for pagination (default: 0) |
count | Number of campaigns to return (default: 10) |
Example: To return the first 10 campaigns: startIndex=0, count=10
Sample request
Multiple filters
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups/list' \ --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' \ --data ' { "advertiserId": 1, "campaignId": 1, "Filter[name]": ["string"], "Filter[status]": "string", "Filter[lastModifiedDate]": "string", "Filter[adGroupId]": [1, 2], "startIndex": 0, "count": 10 } 'Response details
What this response returns
A paginated list of ad groups and their associated delivery configuration.
Key fields to use
-
campaignId
Identifies the parent campaign. -
adGroupId
Unique identifier for the ad group. Used when:- Updating ad groups
- Updating status
- Managing creative associations
-
status
Current lifecycle state. Use this field to determine:- Delivery eligibility
- Available lifecycle actions
- Update eligibility
-
targeting
Contains audience, contextual, keyword, run-of-site, and geotargeting configuration. Use this field to:- Validate targeting setup
- Troubleshoot delivery issues
- Confirm audience strategy
-
budgetType
Defines how spending is controlled. Use this field to understand:- Daily budget behavior
- Total budget behavior
- Delivery pacing configuration
-
attributesSetOnAdGroupLevel
Determines where budget, schedule, and delivery settings are managed. Iftruethese attributes were set on the ad group-level. Iffalse, these attribues were set at the campaign-level. Use this field before performing budget or schedule updates. -
code
Overall operation result (success,failure) -
details
Validation messages, processing feedback, or failure details. -
message
Optional. High-level, human-readable summary of the error when available. -
errors
Detailed information about one or more errors. This is an array object with fields:field,errorType,description
Error Handling
If the request or an individual item fails, the response includes error information to help identify the issue and determine the corrective action. Use errorType for the error condition, field for the affected request field when applicable, and description for an explanation of the error and, when available, guidance on how to resolve it.
For the complete error response schema and endpoint-specific response definitions, see the API Reference. For guidance on HTTP status codes and how clients should handle them, see API status codes and error handling.
Sample response
Successful response
{ "totalResults": 2, "response": [ { "campaignId": 1, "adGroupId": 1, "adGroupExtId": 1, "name": "string", "status": "string", "startDate": "string", "endDate": "string", "budgetType": "string", "deliverySpeed": "string", "dailyBudget": 0, "totalBudget": 0, "rateType": "string", "frequencyCapDay": 0, "frequencyCapWeek": 0, "frequencyCapMonth": 0, "baseBid": 0, "maxBid": 0, "targeting": { "and": [ { "behavioral": [ { "audienceType": "RETAIL", "attribute": "HISTORICAL", "id": 1, "name": "tropicana", "mappingType": "PRODUCT_CATEGORY" }, { "audienceType": "RETAIL", "attribute": "HISTORICAL", "id": 5, "name": "sprite", "mappingType": "PRODUCT_FAMILY" } ] }, { "geoTargets": [ { "id": 2, "name": "Alabama", "locationType": "STATE" }, { "id": 3, "name": "Alaska", "locationType": "STATE" }, { "id": 10, "name": "Abbeville", "locationType": "CITY" } ] } ] }, "creationDate": "string", "lastUpdatedDate": "string", "attributesSetOnAdGroupLevel": true, "creativeRotationMode": "string", "mediaType": "BANNER" }, { "campaignId": 2, "adGroupId": 2, "adGroupExtId": 2, "name": "string", "status": "string", "startDate": "string", "endDate": "string", "budgetType": "string", "deliverySpeed": "string", "dailyBudget": 0, "totalBudget": 0, "rateType": "string", "frequencyCapDay": 0, "frequencyCapWeek": 0, "frequencyCapMonth": 0, "baseBid": 0, "maxBid": 0, "targeting": { "and": [ { "behavioral": [ { "audienceType": "RETAIL", "attribute": "HISTORICAL", "id": 1, "name": "tropicana", "mappingType": "PRODUCT_CATEGORY" }, { "audienceType": "RETAIL", "attribute": "HISTORICAL", "id": 5, "name": "sprite", "mappingType": "PRODUCT_FAMILY" } ] }, { "geoTargets": [ { "zipCode": "35004" } ] } ] }, "creationDate": "string", "lastUpdatedDate": "string", "attributesSetOnAdGroupLevel": true, "creativeRotationMode": "string", "mediaType": "VIDEO" } ]
}Sample response - failure
[ { "code": "failure", "details": [ "string" ], "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]Using the response
The fields returned by this endpoint can be used to support several downstream workflows.
| If you need to... | Review |
|---|---|
| Determine the current lifecycle state | status |
| Prepare an ad group update | Current configuration + adGroupId |
| Determine where budget and schedule are managed | attributesSetOnAdGroupLevel |
| Review the current targeting strategy | targeting |
| Review bidding configuration | baseBid, maxBid |
| Review ad group flight dates | startDate, endDate |
| Investigate delivery issues | Status, targeting, budget, schedule, and creative associations |
Creative associationsCreative associations are managed and retrieved separately from the ad group itself. Use the List Ad Group Creative Associations API to review which creatives are attached to an ad group and their associated delivery configuration.
What happens next
After retrieving the current ad group configuration:
- Modify ad group configuration → Update Ad Groups
- Change delivery state → Update Ad Group Status
- Review attached creatives → List Ad Group Creative Associations
- Review configuration ownership → Campaign vs Ad Group Configuration Rules
- Understand lifecycle behavior → Lifecycle States & Statuses
Delivery troubleshooting
If an ad group is not delivering as expected, review:
A successful update confirms that the ad group changes were accepted. If the ad group still isn't delivering, check its current status and the conditions required for delivery before making additional updates.
Confirm the update
Check the response from the update request to confirm that the changes were accepted. Omitted fields retain their existing values.
Check the ad group status
Retrieve the ad group and review its current lifecycle and delivery status. Some status changes are handled automatically by the ad platform when delivery requirements are met.
Review delivery requirements
Verify that the ad group has valid targeting, creative, budget, dates, and other required configuration before troubleshooting further.
Related pages
Updated 25 days ago
