## Overview The [Reporting API](https://dev.kevel.co/v1.0/reference#reporting-api-overview) enables you programmatically pull Custom and Scheduled Reports. In the API, " _Custom Reports_" may also be referred to as " _Queued Reports_". > 📘 > > ### Note > > All reports generated through the UI or API have a lifetime of 10 days. These reports expire after 10 days and need to be regenerated. ## Creating a Custom Report with the Kevel API 1. Ping the [Create Queued Report](https://dev.kevel.co/reference/queued-reports#create-queued-report) endpoint with details inside of a `criteria` object. 2. Add any GroupBy fields in a `GroupBy` object as a list of strings. 3. Add any Filter fields in a `Parameters` object as a list of Crit objects. 4. Add any Exclude Filter fields in a `ExcludeParameters` object as a list of Crit objects. 5. Wait for the GUID in the response. 6. Make a GET request to the [Poll for Queued Report](https://dev.kevel.co/reference/queued-reports#poll-for-queued-report-result) endpoint to retrieve the data. This example pulls a report that; - Is for January 2017 - Broken down by day and campaigns - Filtered by Advertiser 12 ("Nike") JSON ```json { "StartDateISO": "2017-01-01T00:00:00", "EndDateISO": "2017-01-31T00:00:00", "GroupBy": ["day","campaignId"], "Parameters": [{"brandId": 12}] } ``` In the response you would receive the following response: JSON ```json { "Id": "a87ece06-28cd-4267-9314-e830af7eaa12" } ``` You would then append the response and then make another GET request to the [Poll for Queued Report](https://dev.kevel.co/reference#poll-for-queued-report-result) endpoint: `https://api.kevel.co/v1/report/queue/a87ece06-28cd-4267-9314-e830af7eaa12` This request will return the following report: JSON ```json { "Id":"b0e0v47-be95-4f4e-8d01-090xx55gg44", "Status":2, "Result":{ "StartDateISO": "2017-01-01T00:00:00", "EndDateISO": "2017-01-31T00:00:00", "Critiera":[ ], "LoginId":0, "Records":[ { "Impressions":51431687, "Clicks":63328, "Events":{ "1":29, "2":8 }, "Revenue":114610.83561739461402407011453, "TrueRevenue":89415.3015, "Date":"2017-01-01T00:00:00Z", "FirstDate":"2017-01-01T00:00:00Z", "LastDate":"2017-01-31T00:00:00Z", "CTR":0.1231303184746788492471576900, "Details":[ { "Title":"Name of My Flight ROS CPA", "Impressions":107580, "Clicks":22, "FraudulentClicks":0, "Events":{ "1":1, "2":1 }, "Revenue":200.000, "TrueRevenue":400.0, "Date":"2014-03-07T00:00:00Z", "FirstDate":"2014-03-01T00:00:00Z", "LastDate":"2014-03-31T00:00:00Z", "CTR":0.0204498977505112474437627800, "AdjustedCTR":0, "Details":[ ], "Grouping":{ "OptionId":171761, "BrandId":9396, "CampaignId":91385, "SiteId":0, "ZoneId":0, "CreativeId":0, "PublisherAccountId":0, "AdTypeId":0, "ChannelId":4811, "Date":6042, "DateType":"month", "MetroCode":0, "PriorityId":0, "RateTypeId":5, "Price":"200" }, "eCPM":3.7181632273656813534114147611 }, { "Title":"Another Flight CPM", "Impressions":33994, "Clicks":49, "Events":{ ... ``` > 🚧 > > ### Caution > > All `StartDateISO` and `EndDateISO` requests should use ISO 8601 midnight GMT, such as: '2016-06-01T00:00:00' or '2016-06-01T00:00:00Z'. ## GroupBy and Parameter Fields - Optional In the Reporting API, Group By options are under the `GroupBy` object, while the Filter fields are under `Parameters`. If you haven't already, please review the [Custom Report Fields](https://dev.kevel.co/docs/custom-reports#section-report-filtering-options) for an overview of these parameters. | Name | Description | | ------------ | ----------------------------------------------------------- | | `day` | Calendar day. `GroupBy` only. | | `week` | Calendar week. `GroupBy` only. | | `month` | Calendar month. `GroupBy` only. | | `brandId` | The Advertiser's ID. Pull those [here](https://dev.kevel.co/reference#list-advertisers). | | `campaignId`| The Campaign's ID. Pull those [here](https://dev.kevel.co/reference#list-campaigns). | | `flightId` | The Flight's ID. Pull those [here](https://dev.kevel.co/reference#list-flights) Includes price data when used as a Group By. | | `flightWithoutPrice` | Includes flight data only when used as a Group By. `GroupBy` only. | | `creativeId`| The Creative's ID. Pull those [here](https://dev.kevel.co/reference/creative#list-creatives) | | `adTypeId` | Ad Type / Size. Pull those [here](https://dev.kevel.co/reference#list-ad-types). | | `siteId` | The Site's ID. Pull those [here](https://dev.kevel.co/reference#list-sites). | | `zoneId` | The Zone's ID. Pull those [here](https://dev.kevel.co/reference#list-zones). | | `countryCode`| The Country's code. Pull those [here](https://dev.kevel.co/reference#list-geo-codes). | | `metroCode` | The Metro's code. Pull those [here](https://dev.kevel.co/reference#list-metro-codes-in-region). | | `keyword` | Keywords being targeted. Each keyword is a value in a key value pair: `{"keyword":"foo"}`. | | `channelId` | The Channel's ID. Pull those [here](https://dev.kevel.co/reference#list-channels). `Parameters` only. | | `city` | The name of a city. Must be an exact match. | | `regionCode`| The Region's code. Pull those [here](https://dev.kevel.co/reference/geo-targeting-endpoints-1#list-regions-in-country). Must also filter or group by Country. | | `modelName` | The name of the device model (e.g. iPad for tablet). | | `brandName` | Device Brand (e.g. Apple, Google, Mozilla). | | `advertisedOs`| Operating System (e.g. iOS, Android, Windows, macOS, Linux) | | `osMajorVersion`| OS Major Version (e.g. 15 for iOS 15.5). | | `osMinorVersion`| OS Minor Version (e.g. 5 for iOS 15.5). | | `browser` | Browser (e.g. Chrome Desktop or Safari). | | `browserMajorVersion`| Browser Major Version (e.g. 104 for Chrome 104.0). | | `browserMinorVersion`| Browser Minor Version (e.g. 0 for Chrome 104.0). | | `formFactor`| Device Form Factor (e.g "tablet" or "desktop"). > 📘 > > ### Note > > For `creativeId`, make sure you use the ID associated with the Creative, not the ID associated with the Ad (Creative Flight Maps ID).