What You Can Group & Filter By

👍

Information

When grouping/filtering by region, be sure to also group/filter by countryCode.

When Keyword is used in inventory reports only Selections will be returned in the results, not ADRs.

👍

Information

Using any of the following ID "GroupBy" dimensions:

• "flightId", "advertiserId", "campaignId", "publisherAccountId", "creativeId", "adId", "channelId", "priorityId", "adTypeId", "siteId", "zoneId"
• "promotedProductSkuId", "promotedProductMainCategoryId", "promotedProductBranId", "promotedProductMerchantId", "purchasedProductSkuId", "purchasedProductMainCategoryId", "purchasedProductBranId", "purchasedProductMerchantId",

will result in returning the corresponding name field e.g. "flightId"->"Flight" in Records[]->Details[]->Grouping, as in the example response.

Important Troubleshooting Notes

1. Reports that are grouped by Keyword AND Country or Metro AND include a longer than 31 day time span are too large to be queued.

2. Keywords can be a performance or inventory type dimension.

   1. When Keyword is sent as the only GroupBy property or when combined with other Inventory GroupBy properties, you will get Request Keywords. Request Keywords include ALL keywords values that were sent in the decision request.
   2. When Keyword is sent in combination with any Performance GroupBy property you will get Matching Keywords. Matching Keywords include ONLY keywords from the decision request that were used to match the selected Ad, found at the Flight or Ad level.

3. If the optionId GroupBy is chosen, the report will also be grouped by RateTypeId. This is to meant to break out data on separate lines if the flight has changed RateType during the time period.

4. FlightId will be returned as OptionId in the report.

5. Reports that GroupBy hour cannot use a time frame longer than 35 days from the present.

6. Reports may not be queued that groups by or filters by both Keywords and Region or City.

7. Availability of certain dimensions:

   1. Device dimensions (modelName, brandName, advertisedOs,osMajorVersion, osMinorVersion, browser, browserMajorVersion, browserMinorVersion, formFactor) are not available for "request" metrics. In other words, it is limited to performance reports and is currently not supported for inventory reports. Additionally, osMajorVersion, and osMinorVersion only have data from Oct 1, 2022, querying these dimensions prior to that date will return an error message.
   2. (DEPRECATED) Product dimensions (productSkuId, productMainCategoryid,productBrandId, productMerchantId) are not available for "request" metrics. In other words, it is limited to performance reports and is currently not supported for inventory reports. Product dimensions only have data from Oct 1, 2022, querying these dimensions prior to that date will return an error message.
   3. Promoted/Purchased Product dimensions (promotedProductSkuId, promotedProductMainCategoryId, promotedProductBrandId, promotedProductMerchantId, purchasedProductSkuId, purchasedProductMainCategoryId, purchasedProductBrandId, purchasedProductMerchantId) are not available for "request" metrics. In other words, it is limited to performance reports and is currently not supported for inventory reports. Product dimensions only have data from 14th August 2024 querying these dimensions prior to that date will return an error message.

8. For device reporting to be accurate, the client's UA needs to be passed through to Kevel via the User-Agent header if the customer is proxying events through their server. Failure to do so might cause inconsistent attribution, resulting in e.g. clicks without impressions, as one is not attributed to the same device.

9. Ad Decision Request, Selection Request totals are only available for Inventory Type GroupBy properties, and only in the default TimeZone (UTC).

10. Report becomes a performance type report as soon as any Performance dimension/ GroupBy is included.

Time Zones

1. Reports can be generated in various Time Zones by including "TimeZone" as a body param in the request body.
2. Supported values can be found here
3. Default value is UTC
4. Including a non-default Time Zone means that you will not get request metrics (Ad Decision Requests, Selection Requests, Fill Rate, etc.) in your results.

Report Start Date and End Date

1. Start date can be set using the following body parameters: StartDate or StartDateISO
2. End date can be set using the following body parameters: EndDate or EndDateISO
3. All of these params accept dates in the following formats:
   1. ISO 8601 e.g. YYYY-MM-DDTHH:MM:SS
   2. month/day/year e.g. MM/DD/YYYY
4. When using ISO 8601 format and grouping by day, week, monthor total (no date GroupBy) the date will default to the date that is set, regardless of what is set in the hour, minutes and seconds sections. Ex. Setting an EndDate of 2024-03-04T00:00:00 will include all of the data for March 4th.
5. When using ISO 8601 format and grouping by hour the hour value will be used to generate the report. ex. 2024-01-31T10:00:00 would set the start or end date to the 10th hour of January 31st.
   1. Hour is the most granular level of date grouping we currently support
6. End dates are inclusive.

Report Creation Errors

All errors are wrapped in an {"Error"} object.

{"Validation errors":{"CustomizedCsvColumnNames":"CustomizedCsvColumnNames not an array"}}

{"original": "Clicks",
"new": "Customized Clicks"}