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
Definition of Retrievable Reports
| reportType | Description | Onsite Display | Offsite Display |
|---|---|---|---|
| campaign | Provides overall performance metrics at the campaign level | ✅ Yes | ✅ Yes |
| lineItem | Provides ad group level performance metrics. | ✅ Yes | ✅ Yes |
| tactic | Provides tactic level performance metrics. | ✅ Yes | ✅ Yes |
| sku | Provides item level performance for items in the campaign's itemset | ✅ Yes | ✅ Yes |
| bid | The performance of bids for on-site display auction campaigns | ✅ Yes | ❌ No |
| newBuyer | Analyzes buying frequency of ad exposed shoppers | ✅ Yes | ✅ Yes |
| creative | Provides performance insights at the creative level | ✅ Yes | ❌ No |
| basketAnalysis | Shows 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 |
| ivtViewability | Provides MRC accredited Invalid Traffic & Viewability metrics. Report applicable only for Onsite display | ✅ Yes | ❌ No |
| salesLift | Measures 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
| Parameter | Description | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | The ID of the advertiser | integer | Y | Unique numeric identifier |
| startDate | The 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 | date | Y | Date should be in format: yyyy-MM-dd |
| endDate | The last day to be considered in the performance report snapshot. It cannot be the current date. Note:
| date | Y | Date should be in format: yyyy-MM-dd |
| attributionWindow | Window for attribution Note: attributionWindow is applicable only when reportType = sku | string | Optional and applicable only for sku report | Allowed Values:
|
| salesChannel | Sales channel for the transaction Note: salesChannel is applicable only when reportType = sku | string | Optional and applicable only for sku report | If specified, the metrics applicable for the specified sales channel are returned. Allowed Values: stores, online, acc
|
| itemsetType | Type of item set Note: itemsetType is applicable only when reportType = sku | string | Optional and applicable only for sku report | If specified, the metrics applicable for the specified itemsetType are returned. Allowed Values: halo, featured, total
|
| reportType | Type of report to be retrieved | string | Y | Types of Report: campaign, lineItem, tactic, sku, bid, newBuyer, creative, salesLift, basketAnalysis, ivtViewabilityNote: basketAnalysis, ivtViewability reports are available only for Onsite display |
| reportMetrics | Choose 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 | string | N | Please refer to the table “Definition of Various Parameters Generated Across the Snapshot Reports” for detailed information on report metrics |
| scope | scope 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 | string | N | Possible values: CAMPAIGN, CAMPAIGN_GROUP
|
| buyerLookbackWindow | Lookback 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> | N | Allowed 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.
-
No-data behavior: If a report is generated successfully but no data is available for a metric or field, the report displays
0. -
Date range behavior: Reporting data is returned for the
startDateandendDatespecified in the request, except where a report-specific rule states otherwise. -
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. -
Report type values:
reportTypemust be one of the supported enum values:campaign,lineitem,tactic,sku,newBuyer,bid,creative,ivtViewability,basketAnalysis,salesLiftbidreports are refreshed near real-time.
-
Field applicability and defaults:
Field Applies To Allowed Values Default Validation / Behavior itemsetTypeskuonlyfeatured,halo,totalNone Optional. If provided for any report type other than sku, return a validation error.attributionWindowskuonlydays14,days30None Optional. If provided for any report type other than sku, return a validation error.salesChannelskuonlyonline,stores,accNone Optional. If provided for any report type other than sku, return a validation error.buyerLookbackWindownewBuyeronly[" months6"], ["months12"], ["months18"], ["months24"], ["months36"]months12Optional. If omitted for newBuyer,months12is used. If provided for any report type other thannewBuyer, return a validation error. -
buyerLookbackWindowRules:buyerLookbackWindowis optional and is supported only whenreportType = newBuyer.- Default Behavior: If
buyerLookbackWindowis 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
buyerLookbackWindowvalue is provided in the request.
- The following buyer lookback windows are supported only for eligible new campaigns
-
Date Range Behavior for New Buyer Reports:
Campaign Type Behavior Eligible new campaigns (start date >= 2026-06-01)using last-touch attributionNew Buyer data is returned for the startDateandendDatespecified in the request.Older or ineligible campaigns New 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
| Field | Description | Optional field/Nullable? | Type | Possible values |
|---|---|---|---|---|
| code | The response code can have following values:
Click here for more information about Status Codes and Errors | N | string | success, failure |
| details | Details will populate success or error message depending upon value of code. | N | string | |
| snapshotId | ID of the snapshot. This will be returned only when code=success | Y | string | |
| jobStatus | It is an indicator to confirm status of snapshot generation.The possible values of jobStatus are: pending, processing, done, failed, expired | Y | string | |
| message | High-level summary of the error, when available. | Y | string | |
| errors | Detailed information about one or more errors, including the affected field (when applicable), error code, and a human-readable description. | Y | array<object> |
errors array object details
| Field | Description | Optional field/Nullable? | Type | Possible values |
|---|---|---|---|---|
| field | JSON field associated with the error. Omitted if the error applies to the request as a whole. | Y | string | |
| errorType | Machine-readable error code that uniquely identifies the error condition. Applications should use this value for error handling logic. | N | string | |
| description | Human-readable explanation of the error, including why the request failed and, when possible, how to resolve it | N | string |
Updated 14 days ago
