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 endpoint

This 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


Request 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 UsedResult
No FilterAll ad groups in the campaign
adGroupIdSpecific ad groups (max 25 IDs)
nameExact ad group name
statusAd groups in a specified lifecycle state
lastModifiedDateAd groups created or updated on or after the specified date

Supported lifecycle states

  • draft
  • scheduled
  • live
  • paused
  • completed
  • archived

Pagination

ParameterDescription
startIndexstarting index for pagination (default: 0)
countNumber 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. If true these attributes were set on the ad group-level. If false, 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 statestatus
Prepare an ad group updateCurrent configuration + adGroupId
Determine where budget and schedule are managedattributesSetOnAdGroupLevel
Review the current targeting strategytargeting
Review bidding configurationbaseBid, maxBid
Review ad group flight datesstartDate, endDate
Investigate delivery issuesStatus, targeting, budget, schedule, and creative associations
📌

Creative associations

Creative 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:


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.

1

Confirm the update

Check the response from the update request to confirm that the changes were accepted. Omitted fields retain their existing values.

2

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.

3

Review delivery requirements

Verify that the ad group has valid targeting, creative, budget, dates, and other required configuration before troubleshooting further.


Related pages


Did this page help you?