## What You Can Group & Filter By

| Type | Property | Group By (<br>`GroupBy`<br>) | Filter By (<br>`Parameters`<br>) | Exclude Filter By (<br>`ExcludeParameters`<br>) |
| --- | --- | --- | --- | --- |
| Date Grouping | `hour`,`day`, `week`, `month` | Yes | No | No |
| Performance Dimensions | `brandId`, `campaignId`, `optionId`, `creativeId`, `publisherAccountId`,`modelName`, `brandName`, `advertisedOs`, `osMajorVersion`, `osMinorVersion`, `browser`, `browserMajorVersion`, `browserMinorVersion`, `formFactor`, `bidModifierType`, `bidModifierValue`, `bidModifierMultiplier`, `bidModifierPrice`, `keyword`(matching keywords) | Yes | Yes | Yes |
| Performance Dimensions | `adId` | Yes | No | No |
| (DEPRECATED) Product Performance Dimensions | `productSkuId`, `productMainCategoryId`, `productBrandId`, `productMerchantId` | Yes | Yes | Yes |
| (NEW) Promoted/Purchased Product Performance Dimensions | `promotedProductSkuId`, `promotedProductMainCategoryId`, `promotedProductBrandId`, `promotedProductMerchantId`, `purchasedProductSkuId`, `purchasedProductMainCategoryId`, `purchasedProductBrandId`, `purchasedProductMerchantId` | Yes | Yes | Yes |
|  |  |  |  |  |
| Inventory Dimensions | `siteId`,`zoneId`, `adTypeId`,`countryCode`,<br>`metroCode`,`regionCode`, `city`,`keyword*`(request keywords) | Yes | Yes | Yes |

### 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.

## 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 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 group 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](https://dev.kevel.com/docs/time-zones-1#available-time-zones-strings)
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`, `month`or 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.
6. End dates are inclusive.

## Report Creation Errors

| Error Code | JSON Response | Error Description |
| --- | --- | --- |
| 500 | `"Server Error"` | Report queuing is unavailable. [Check the status page](http://status.kevel.co/) for details. If none are available, contact Kevel support. |
| 403 | `"Invalid API key"` | No API key in request, or the key does not belong to an account. |
| 400 | `"Missing required parameter: criteria"` | No `criteria` object in the request. |
| 400 | `{"Validation errors": {"JSON parse error": <error-detail-string>}}` | Invalid JSON passed in the request. Includes a string with the parsing error. |
| 400 | `{"Validation errors": {"End": "Start must precede end"}}` | The Start Date is after the End Date. |
| 400 | `{"Validation errors": {"StartDate": "StartDate must not be specified when StartDateISO is."}}` | Both `StartDate` and `StartDateISO` are supplied. |
| 400 | `{"Validation errors": {"EndDate": "EndDate must not be specified when EndDateISO is."}}` | Both `EndDate` and `EndDateISO` are supplied. |
| 400 | `{"Validation errors":{"StartDate":{"reason":"Invalid date format: 'xxxxx' is malformed at 'xxxxx'. Dates should be formatted like dd/MM/yyyy, e.g. 31/12/2016"}}` | `StartDate` or `EndDate` are not formatted correctly. |
| 400 | `{"Validation errors":{"StartDateISO":{"reason":"Invalid date format: 'xxxxx' is malformed at 'xxxxx'. Dates should be formatted like yyyy-MM-dd'T'HH:mm:SS, e.g. 2016-12-31T00:00:00"}}` | `StartDateISO` or `EndDateISO` are not formatted correctly. |
| 400 | `{"Validation errors":{"GroupBy":{"reason":"GroupBy not an array"}}}` | A parameter (such as `GroupBy`) uses the wrong data type. |
| 400 | `{"Validation errors":{"GroupBy":{"reason":"GroupBy contains some elements that are not strings.","elements":[1234,"campaignId"]}}}` | One of the `GroupBy` elements uses the wrong data type. |
| 400 | `{"Validation errors":{"GroupBy":{"fields": ["flightid"],"reason":"Invalid GroupBy fields. Valid values must be one of 'adtypeid', 'brandid', 'campaignid', 'countrycode', 'creativeid', 'adid' 'day', 'keyword', 'metrocode', 'month', 'optionid', 'publisheraccountid', 'siteid', 'week', 'zoneid','modelName', 'brandName', 'advertisedOs , 'osMajorVersion', 'osMinorVersion', 'browser', 'browserMajorVersion', 'browserMinorVersion', 'formFactor', 'productSkuId', 'productMainCategoryid', 'productBrandId', 'productMerchantId'."}}}` | Invalid `GroupBy` element. |
| 400 | `{"Validation errors":{"Parameters":{"reason":"Parameters not an array.","value":1234}}}` | `Parameters` is not an object. |
| 400 | `{"Validation errors":{"Parameters":[{"param":{},"reason":"parameter object must have one property"}]}}` | `Parameters` must have at least one property. |
| 400 | `{"Validation errors":{"Parameters":[{"name":"foo","reason":"invalid parameter name"}]}}` | Parameter property does not exist. |
| 400 | `{"Validation errors":{"Parameters":[{"parameter":"SiteId","bad-value":"foo","reason":"id parameter value must be a positive integer"}]}}` | Parameter value must be an integer. |
| 400 | `{"Validation errors":{"Parameters":[{"parameter":"metroCode","bad-value":1000,"reason":"metroCode, countryCode, and keyword values must be strings"}]}}` | Parameter value must be a string (in the case of `metroCode`, `countryCode`, and `keyword`). |
| 400 | `{"Validation errors":{"ReportTooLarge":"A report grouping by Keyword and either Country or Metro cannot exceed a one month (31 day) span."}}` | Reports that are grouped by Keyword and Country/Metro AND include a longer than 31 day time span cannot be queued. |
| 400 | `{"Validation errors":{"ReportTooLarge":"An hourly report can only be requested for dates within the last 35 days."}}` | Reports that use the hourly date group can only be requested for a period within the past 35 days Or when a report exceeds 1.3 million rows in total. |
| 400 | `{"Error":{"Validation errors":{"TimeZone":"Time Zones are not supported on keyword reports."}}}` | Reports cannot use both keywords and non-GMT (UTC) timezones. |
| 400 | `{"Validation errors":{"CustomizedCsvColumnNames":"CustomizedCsvColumnNames not an array"}}` | The value of `CustomizedCsvColumnNames`must be an array. |
| 400 | `{"Validation errors":{"CustomizedCsvColumnNames":"CustomizedCsvColumnNames must be an array of objects, each with exactly two keys, \"original\" and \"new\", whose values are strings"}}` | The value of `CustomizedCsvColumnNames` must be an array of objects with the following format: `{"original": "Clicks","new": "Customized Clicks"}` |

## Example Request

```bash
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type:application/json" https://api.kevel.co/v1/report/queue --data-binary '{"StartDateISO": "2017-01-01","EndDateISO": "2017-05-16","GroupBy":["campaignId"], "Parameters":[{"siteId":123456}]}'
```

```json
{
  "Id": "a87ece06-28cd-4267-9314-e830af7eaa12"
}
```