Guides

Entity snapshots

Generate Entity Snapshots to retrieve campaign and ad group metadata for reporting.

Overview

Entity Snapshots provide configuration, hierarchy, and status information for advertiser campaigns in a downloadable JSON file.

Use this endpoint to synchronize campaign metadata, validate entity configuration, or support reporting data joins.

Entity Snapshots do not return campaign performance metrics.

Availability

Supported for Onsite Display and Offsite Display (Walmart DSP).

Onsite and Offsite advertisers use separate advertiser IDs. Submit separate snapshot requests when retrieving metadata for both media solutions.

ℹ️

Entity status differs by media solution

Onsite Display and Walmart DSP use different entity status values. The entityStatus request filter maps to the applicable statuses for each solution.

See the entity status mapping below.

How it works

Submit an Entity Snapshot request specifying the advertiser, entity types, and optional status filter.

The API creates an asynchronous snapshot job and returns a snapshotId.

Use the shared Snapshot Reporting workflow to retrieve the generated file.

Before you begin

  • Valid advertiserId
  • Reporting read access for the advertiser
  • Determine whether the request is for Onsite Display or Walmart DSP
  • Select the campaign and/or ad group entity types to retrieve
  • Determine which entity statuses should be included

Endpoint

POST /api/v1/snapshot/entity

View technical specifications

Request details

How this request is used

Use this endpoint to generate a file containing campaign or ad group metadata for an advertiser.

Key fields and behaviors

  • entityTypes
    Selects the entities to include. Supported values include campaign and lineItem. Multiple entity types can be requested together. Multiple entity types can be included in one request. For example, use ["campaign", "lineItem"] to retrieve both campaign and ad group metadata.
  • entityStatus
    Filters entities by status using active, inactive, or all. The resulting statuses differ by media solution.

Entity status mapping

The status values included in each filter differ between Onsite and Offsite Display.

entityStatusOnsite DisplayOffsite Display
activeLIVE, SCHEDULEDACTIVE
inactiveDRAFT, PAUSED, COMPLETEDINACTIVE
allLIVE, SCHEDULED, DRAFT, PAUSED, COMPLETEDACTIVE, INACTIVE, PAUSED, COMPLETED

These are the mappings documented for the Entity Snapshot API. They should not be assumed to represent every lifecycle status used elsewhere in the advertising platform.

Request header: Expression vs. Flat targeting format in line item entity snapshots

x-targeting-format: "FLAT", /*FLAT, EXPRESSION. Applicable only for lineItem entity reports*/

Specifies the JSON schema used to evaluate and return the targeting object. Two values can be used in this header:

  • EXPRESSION
    The targeting object is represented in the legacy logical expression structure, utilizing nested and / not operators.
  • FLAT
    The targeting object is represented using the flattened schema using explicit include and exclude arrays.

Sample request

Create an Entity Snapshot
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/snapshot/entity' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: <signature>' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: <consumer_id>' \ --header 'WM_CONSUMER.intimestamp: <timestamp>' \ --data '{ "advertiserId": 600001, "entityStatus": "active", "entityTypes": ["campaign"] }'

To retrieve both campaign and ad group metadata, include both supported entity types:

{ "advertiserId": 600001, "entityStatus": "all", "entityTypes": ["campaign", "lineItem"]
}

Response details

What this response returns

A successful request creates an asynchronous snapshot generation job.

  • code
    Indicates if submission was successful
  • snapshotId
    Identifier used to retrieve the snapshot job (save to use later).
  • jobStatus
    Current processing status
  • details
    Additional information associated with the request.

Sample response

Entity Snapshot request accepted
[ { "code": "success", "snapshotId": "1", "details": "", "jobStatus": "pending" }
]

The creation response does not contain the entity metadata file. Use the returned snapshotId to retrieve the completed snapshot.

Understanding the generated file

Entity Snapshots contain JSON data describing the requested entities.

The output structure depends on the selected entityTypes and the advertiser's media solution.

Campaign metadata

Campaign objects can include identifiers, names, statuses, dates, objectives, and configuration settings.

Example campaign metadata
{ "campaigns": [ { "campaignId": 734, "campaignExtId": 734, "name": "AdGroup Delivery Speed Updates", "campaignType": "NGD", "status": "DRAFT", "advertiserId": 0, "creationDate": "2024-10-15T16:49:35.293-04:00", "lastUpdatedDate": "2024-10-16T01:19:33.990-04:00", "objective": "ENGAGEMENT", "attributesSetOnAdGroupLevel": true, "mediaType": "BANNER" } ]
}

Ad group metadata

Ad group objects are returned under lineItems.

They can include campaign relationships, entity identifiers, delivery settings, budgets, bids, targeting, and other configuration details.

Example ad group metadata
{ "lineItems": [ { "campaignId": 944108, "lineItemId": 1265197, "lineItemExtId": 1265197, "name": "Test-video", "status": "DRAFT", "startDate": "2025-04-10T00:00:00.000-04:00", "endDate": "9999-12-30T00:00:00.000-05:00", "budgetType": "DAILY", "totalBudget": 0.0, "dailyBudget": 0.0, "rateType": "CPM", "deliveryRateType": "EVENLY", "maxBid": 120.0, "attributesSetOnAdGroupLevel": true, "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "mediaType": "VIDEO" } ]
}

Offsite metadata

Walmart DSP Entity Snapshots use Offsite-specific entity identifiers and status values.

For example, an Offsite line item may return:

Example Offsite line item
{ "lineItems": [ { "name": "Test Lineitem 1", "lineItemId": "abcde12-34fg-567h-ijk8-lmnopqr9", "lineItemExtId": "abcdefg", "campaignId": "abcde12-34fg-567h-ijk8-lmnopqr9", "campaignExtId": "abcdefg", "status": "ACTIVE" } ]
}

These examples illustrate selected fields. Actual files may include additional metadata depending on the entity and media solution.

Common issues

  • Using an Onsite advertiser ID for an Offsite request, or vice versa
  • Requesting an unsupported entityTypes value
  • Assuming entityStatus maps to the same lifecycle values across media solutions
  • Expecting performance metrics in an Entity Snapshot
  • Assuming the creation response contains the generated JSON file
  • Confusing lineItem with a separate campaign-level entity
  • Not using filters to reduce report size

What happens next

After the Entity Snapshot request is accepted:

  1. Store the returned snapshotId.
  2. Use Retrieve Snapshots to check processing status.
  3. When jobStatus=done, download the generated JSON file.
  4. Use the metadata to synchronize campaign hierarchy, validate configuration, or join with performance reports.

Related pages

Updated about 1 hour ago

Did this page help you?