Create Report Snapshot

You can request a snapshot file for all performance reporting data available (until the date before current date) for a given advertiser using this method
Reporting data may be delayed by 24 to 48 hours from the time of the request.

Note: The POST functionality is similar for both Onsite and Offsite display

📘

URL: POST /api/v1/snapshot/report


Definition of Retrievable Reports

reportTypeDescriptionOnsite DisplayOffsite Display
campaignProvides overall performance metrics at the campaign level✅ Yes✅ Yes
lineItemProvides ad group level performance metrics.✅ Yes✅ Yes
tacticProvides tactic level performance metrics.✅ Yes✅ Yes
skuProvides item level performance for items in the campaign's itemset✅ Yes✅ Yes
bidThe performance of bids for on-site display auction campaigns✅ Yes❌ No
newBuyerAnalyzes buying frequency of ad exposed shoppers✅ Yes✅ Yes
creativeProvides performance insights at the creative level✅ Yes❌ No
basketAnalysisShows the top 10 online and top 10 in-store categories and sub-categories most frequently purchased together with advertised items in shopper baskets.
Report applicable only for Onsite display

Note: this report is available only in End of Campaign reporting starting 30 days after the campaign ends and is not available for campaigns with spend below $150K
✅ Yes❌ No
ivtViewabilityProvides MRC accredited Invalid Traffic & Viewability metrics.
Report applicable only for Onsite display
✅ Yes❌ No
salesLiftMeasures incrementality of sales after campaign exposure. Sales Lift Reports (SLR) will be available only 30 days after a campaign has ended✅ Yes✅ Yes

📌

Note:

SKU reports can produce very large files. We strongly recommend using a date range of 15 days or fewer (vs. the 60-day limit for other reports); if your ad campaign includes many items, reduce the date range even further to ensure the report completes reliably


Request Parameters

ParameterDescriptionTypeRequiredPossible Values
advertiserIdThe ID of the advertiserintegerYUnique numeric identifier
startDateThe first day to be considered in the performance report snapshot. It cannot be the current date
Note: The reports encompass data starting from midnight (00:00:00 hrs ET) on this particular date
dateYDate should be in format: yyyy-MM-dd
endDateThe last day to be considered in the performance report snapshot. It cannot be the current date.
Note:
  • The reports encompass data until the end of the day (23:59:59 hrs ET) for this particular date
  • If report data is not available for the requested end date, the request will fail, and the response will contain endDate until which the performance report is available
dateYDate should be in format: yyyy-MM-dd
attributionWindowWindow for attribution
Note: attributionWindow is applicable only when reportType = sku
stringOptional and applicable only for sku reportAllowed Values:
  • days14: Report will include 14-day attribution columns If a user selects this value
  • days30: Report will include 30-day attribution columns if a user selects this value
salesChannelSales channel for the transaction
Note: salesChannel is applicable only when reportType = sku
stringOptional and applicable only for sku reportIf specified, the metrics applicable for the specified sales channel are returned.
Allowed Values: stores, online, acc
  • stores: If specified, only metrics prefixed with storeAttributed are returned
  • online: If specified, only metrics prefixed with pickupAttributed, deliveryAttributed are returned
  • acc: If specified, only metrics prefixed with accAttributed are returned
itemsetTypeType of item set
Note: itemsetType is applicable only when reportType = sku
stringOptional and applicable only for sku reportIf specified, the metrics applicable for the specified itemsetType are returned.
Allowed Values: halo, featured, total
  • halo: if specified, only metrics are returned that have “Halo“ in it
  • featured: if specified, only metrics are returned that have “Featured“ in it
  • total: if specified, only metrics are returned that have “Halo“ or “Featured“ in it
reportTypeType of report to be retrievedstringYTypes of Report: campaign, lineItem, tactic, sku, bid, newBuyer, creative, salesLift, basketAnalysis, ivtViewability
Note: basketAnalysis, ivtViewability reports are available only for Onsite display
reportMetricsChoose the metrics type for your snapshot
Note: If you omit this parameter in your request, you will receive all the metrics that are relevant to the selected report type
stringNPlease refer to the table “Definition of Various Parameters Generated Across the Snapshot Reports” for detailed information on report metrics
scopescope is an optional parameter that is ignored for all report types. Partners should omit it, as the API returns the canonical dataset by default.

The field is slated for future deprecation
stringNPossible values: CAMPAIGN, CAMPAIGN_GROUP
  • When reportType is set to campaign, lineItem, sku, or newBuyer, the default value of scope = CAMPAIGN
  • When reportType is set to creative, tactic, ivtViewability or bid: scope = CAMPAIGN_GROUP is not supported and will return an error.
buyerLookbackWindowLookback time frame used to define New Buyers as ad-exposed buyers who have not purchased featured or halo items during that period, measured from the first attributed transaction.
Note: applicable only for New Buyer reports
array<string>NAllowed Values:
["months6"], ["months12"], ["months18"], ["months24"], ["months36"]

Note: For salesLift Report, The selected startDate and endDate must include a window where the campaign was active. Otherwise, no results will be returned.

👉

Rules

  1. No-data behavior: If a report is generated successfully but no data is available for a metric or field, the report displays 0.

  2. Date range behavior: Reporting data is returned for the startDate and endDate specified in the request, except where a report-specific rule states otherwise.

  3. Unsupported field usage: Optional fields are only valid for the report types explicitly listed in this section. If an optional field is provided for an unsupported reportType, the request should return a validation error.

  4. Report type values:

    • reportType must be one of the supported enum values: campaign, lineitem, tactic, sku, newBuyer, bid, creative, ivtViewability, basketAnalysis, salesLift
    • bid reports are refreshed near real-time.
  5. Field applicability and defaults:

    FieldApplies ToAllowed ValuesDefaultValidation / Behavior
    itemsetTypesku onlyfeatured, halo, totalNoneOptional. If provided for any report type other than sku, return a validation error.
    attributionWindowsku onlydays14, days30NoneOptional. If provided for any report type other than sku, return a validation error.
    salesChannelsku onlyonline, stores, accNoneOptional. If provided for any report type other than sku, return a validation error.
    buyerLookbackWindownewBuyer only["months6"], ["months12"], ["months18"], ["months24"], ["months36"]months12Optional. If omitted for newBuyer, months12 is used. If provided for any report type other than newBuyer, return a validation error.
  6. buyerLookbackWindow Rules:

    • buyerLookbackWindow is optional and is supported only when reportType = newBuyer.
    • Default Behavior: If buyerLookbackWindow is omitted for a New Buyer report, the default value is: "buyerLookbackWindow": ["months12"]
    • Supported Values: ["months6", "months12", "months18", "months24", "months36"]
    • Eligibility Rules:
      • The following buyer lookback windows are supported only for eligible new campaigns (start date is on or after 2026-06-01, using last_touch attribution): ["months6", "months18", "months24", "months36"]
      • For older campaigns, the New Buyer report continues to use the default 12-month buyer lookback window, even if another buyerLookbackWindow value is provided in the request.
  7. Date Range Behavior for New Buyer Reports:

    Campaign TypeBehavior
    Eligible new campaigns (start date >= 2026-06-01) using last-touch attributionNew Buyer data is returned for the startDate and endDate specified in the request.
    Older or ineligible campaignsNew Buyer data is returned as campaign-to-date metrics for the lifetime of the line item.

    New Buyer counts for a custom date range represent unique eligible buyers across the full range. A buyer appearing on multiple days is counted once; therefore, the sum of daily counts may differ from the count for the combined range.

Response

FieldDescriptionOptional field/Nullable?TypePossible values
codeThe response code can have following values:
  • success
  • failure

Click here for more information about Status Codes and Errors
Nstringsuccess, failure
detailsDetails will populate success or error message depending upon value of code.Nstring
snapshotIdID of the snapshot. This will be returned only when code=successYstring
jobStatusIt is an indicator to confirm status of snapshot generation.The possible values of jobStatus are: pending, processing, done, failed, expiredYstring
messageHigh-level summary of the error, when available. Ystring 
errorsDetailed information about one or more errors, including the affected field (when applicable), error code, and a human-readable description.Yarray<object> 

errors array object details

FieldDescriptionOptional field/Nullable?TypePossible values
fieldJSON field associated with the error. Omitted if the error applies to the request as a whole.Ystring 
errorTypeMachine-readable error code that uniquely identifies the error condition. Applications should use this value for error handling logic.Nstring 
descriptionHuman-readable explanation of the error, including why the request failed and, when possible, how to resolve itNstring 
🔧

Troubleshooting Tip:

Slow Report Generation: If your report is taking a long time to generate or if the API response times out, try reducing the date range


Did this page help you?