Snapshot Reporting
Generate, retrieve, and download historical performance and entity Snapshot reports.
Overview
Snapshot Reporting APIs generate downloadable files containing historical performance data or campaign and ad group metadata.
Use Snapshot Reporting to support:
- Historical performance analysis, attribution, and reconciliation
- Large-scale reporting exports and BI pipelines
- Campaign and ad group metadata synchronization
- Automated reporting workflows
Snapshot generation is asynchronous. Create a snapshot, check its processing status, and download the generated file when ready.
Availability
| Media solution | Availability |
|---|---|
| Onsite Display | Performance and Entity Snapshots, including self-serve and managed-serve accounts |
| Offsite Display (Walmart DSP) | Performance and Entity Snapshots; available report types and metrics vary |
For report-specific availability, see Report Types.
Snapshot types
Both snapshot types follow the same retrieval and download workflow but return different data.
| Performance Snapshot | Entity Snapshot | |
|---|---|---|
| Purpose | Historical performance and attribution reporting | Campaign and ad group metadata |
| Output | CSV | JSON |
| Data included | Delivery, spend, sales, and other report-specific metrics | Entity identifiers, names, statuses, hierarchy, and configuration |
| Typical use | Reporting pipelines, reconciliation, and analysis | Campaign hierarchy synchronization and metadata joins |
| Create endpoint | POST /api/v1/snapshot/report | POST /api/v1/snapshot/entity |
Performance reporting data is refreshed daily and is typically available through T-1, subject to processing completion.
Entity Snapshots retrieve available campaign and ad group metadata at the time of snapshot generation.
How it works
Performance and Entity Snapshots share the same asynchronous workflow. The endpoint used to create the snapshot determines which data is returned.
Create snapshot
Submit a Performance or Entity Snapshot request and store the returned snapshotId.
POST /api/v1/snapshot/report POST /api/v1/snapshot/entityRetrieve snapshot
Check processing status using snapshotId. When jobStatus is done, retrieve the file URL from details.
GET /api/v1/snapshotDownload and store
Use the returned file URL, advertiserId, and required authentication headers to download and store the file.
Before you begin
- Reporting read access for the advertiser account
- Valid
advertiserId - Determine whether Performance or Entity Snapshot data is needed
- For Performance Snapshots, confirm the supported report type, metrics, and reporting date range
- Check the latest processed reporting date before requesting finalized performance data
Snapshot endpoints
| Workflow | Endpoint | Technical Specifications |
|---|---|---|
| Create Performance Snapshot | POST /api/v1/snapshot/report | View |
| Create Entity Snapshot | POST /api/v1/snapshot/entity | View |
| Retrieve Snapshots | GET /api/v1/snapshot | View |
Snapshot processing and availability
Snapshot generation time depends on the requested data volume and report complexity.
| Consideration | What to expect |
|---|---|
| Processing time | Typically 10–15 minutes; larger requests may take up to 60 minutes. |
| Performance data freshness | Refreshed daily, typically available through T-1. |
| Snapshot completion | jobStatus=done indicates that the generated file is ready. |
| File URL | Returned in the details field of the Retrieve Snapshots response. |
| File availability | Generated files are available for 24 hours after creation. |
Use Get Latest Report Date to confirm the latest processed date before requesting finalized performance data.
Snapshot creation is not file completionA successful snapshot creation request confirms the job was accepted, not that the file is ready.
Use
GET /api/v1/snapshotto check processing status. The file URL becomes available indetailswhenjobStatus=done.
For automated reporting pipelines, confirm the latest available report date before creating Performance Snapshots. Store the returned snapshotId, check processing status until completion, and download generated files promptly to avoid expiration.
Common issues
- Requesting performance data before the reporting date has completed processing
- Treating a successful snapshot creation response as file completion
- Attempting to download before
jobStatus=done - Failing to retrieve the file URL from
details - Omitting the
advertiserIdquery parameter or required authentication headers - Attempting to download a file after its 24-hour availability window
- Assuming Performance and Entity Snapshots return the same data format
What happens next
After downloading a snapshot, ingest the CSV or JSON file into your reporting system.
Performance and Entity Snapshot files can be used together to join historical performance metrics with campaign and ad group metadata.
Related pages
Updated about 3 hours ago
What’s Next
Generate your snapshot request