Support Home > Analytics, Reports & API > API v1.3 – Requesting and Scheduling Reports

API v1.3 – Requesting and Scheduling Reports

DOCUMENT SUPERSEDED: The information that is contained within this document has been superseded. Refer to the current API Reporting support document for the latest integration instructions and procedures.

The Data Access API Integration provides additional reporting tools to supplement those available through the Free App Analytics platform.

The Free App Analytics platform provides extensive tools to track everything from impressions thru post-install events for connected devices. The API reporting method provides advertisers with the programmatic tools to gather performance data on an on-demand or scheduled basis.

For clarity, our support documentation for API v1.3 has been divided into the following sections:

 

This document defines the methods for pulling new reports and creating scheduled reports utilizing the API.

 

NOTE: For details on the parameters available within each report, refer to our Reports Overview support documentation.

Requesting a New Summary Report

A Summary Report is a report showing counters for the traffic requested for a specific timeframe, and grouped by the fields requested in the API call. More than 1 counter can be selected by including multiple “traffic” parameters.

 

Clicks Counters:

  • # clicks
  • # duplicate clicks
  • # clicks matched to impressions
  • # amount spent on clicks

 

Installs Counters:

  • # installs
  • # installs matched to impressions
  • # installs matched to clicks

 

Impression Counters:

  • # impressions
  • Amount spent on Impression

 

Reengagement Counters:

  • # reengagment for

 

Event Counters:

  • # events
  • # revenue generating events
  • Amount of revenue generated

 

NOTE: Event Counters are only available through the API.

 

Traffic Verification Counters:

  • # clicks verified OK
  • # clicks verified NOT OK
  • # impressions verified OK
  • # impressions verified NOT OK

 

WARNING: If Traffic Verification is selected (Summary and Detail Reports) the install_verification column has been removed and new columns related to impression_verification have been added.

 

Filtering The Summary Report:

The Summary Report may be filtered on the following:

  • Country
  • Network
  • Site
  • Campaign
  • Tracker
  • Creative

 

Excluding Columns from Report:

The following columns may be excluded from the Summary Report:

  • Network
  • Site
  • Country
  • Campaign
  • Tracker
  • Creative

 

NOTE: Inclusion and Exclusion filters use OR logic, meaning they cannot be treated like a censor. For example, in the case of an inclusion filter if an install matched both a click and impression it is included if either is of that network. In the case of an exclusion filter, if an install matched both a click and impression it is included if either is NOT of that network.

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/summary

 

Sample Post Data:

{
  "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
  "app_guid": "test-53c9555b06059",
  "time_start": "1450000000",
  "time_end": "1450700000",
  "traffic": [
    "click"
  ],
  "traffic_grouping": [
    "country"
  ],
  "time_series": "1",
  "time_zone": "America/Toronto",
  "traffic_filtering": {
    "network": [
      "120",
      "550"
    ],
    "exclude_country" : [
      "us"
    ]
  },
  "delivery_method": [
    "S3link"
  ],
  "delivery_format": "csv",
  "notify": [
    "test@kochava.com"
  ]
}

 

Successful Response Example:

{
  "status": "queued",
  "report_token": "122245554"
}

 

Error Response Example:

{
  "status": "Error",
  "error": "Error request parameters TimeSerie  missing."
}

Requesting a New Detail Report

A Detail Report is a report showing original data for the traffic requested for a specific time range requested in the API call.

 

WARNING: If Traffic Verification is selected (Summary and Detail Reports) the install_verification column has been removed and new columns related to impression_verification have been added.

 

NOTE: Detail Reports that exceed 5.0 gigabytes in size will be compressed to enable accelerated download.

 

Available Reports:

By using the Traffic key the following reports are available –  click, impression, install, event, reengagement, influencer_imp, influencer_click, collected cost, and fractional.

 

NOTE: For event traffic, the following events are excluded _Install, _Click, _SessionBegin and _SessionEnd.

 

Filtering The Detail Report:

The Detail Report can be filtered on the following:

  • Event Report – event_name (as long as not starting with _) and network
  • Influencer (click and impression) – network
  • Fractional – network (winning)
  • Click/Impression/Reengagment – network, tracker
  • Install – network, country, site and tracker
  • Reengagement Report – event_name

 

NOTE: If a filter is included with the request on events, only that event_name will be selected.

 

Excluding Columns from Report:

The following columns may be excluded from the Detail Report:

Install Detail –

  • Network
  • Site
  • Country
  • Tracker
  • Creative

 

Event Detail –

  • Network

 

Reengagement Detail –

  • Network
  • Site
  • Country
  • Tracker
  • Creative

 

NOTE: Inclusion and Exclusion filters use OR logic, meaning they cannot be treated like a censor. For example, in the case of an inclusion filter if an install matched both a click and impression it is included if either is of that network. In the case of an exclusion filter, if an install matched both a click and impression it is included if either is NOT of that network.

NOTE: In order to view the currency generated by an event in a specific format, such as YEN, add a JSON entry such as:

  • “currency”: “JPY”

 

Two columns will be added to the Event Detail report displaying the currency type and value.

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/detail

 

Sample Post Data:

{
  "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
  "app_guid": "test-53c9555b06059",
  "time_start": "1450000000",
  "time_end": "1450700000",
  "traffic":      ["event"], 
  "traffic_filtering": {
      "event_name": ["eCommerce - ViewDetail", "eCommerce - AddToCart"]
      "exclude_network" : [
          "499"
      ]
    },
  "time_zone":    "Asia/Seoul", 
  "delivery_method": ["S3link"],
  "delivery_format": "csv", 
  "notify":   ["test@kochava.com"] 
}
If you want to see, the revenue generated by the event in Yen (adding 2 columns to the report), you would add the following entry in the json:
          "currency":    "JPY"
for US Dollar, add
          "currency":    "USD"

 

Successful Response Example:

{
  "status": "queued",
  "report_token": "122245554"
}

 

Error Response Example:

{
  "status": "Error",
  "error": "Error request parameters app_guid missing."
}

Requesting a Detail Report with Limited/Reordered Columns

Using this method will return a report with the specified columns in the exact order specified.

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/detail

 

Sample Post Body:

{
  "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
  "app_guid": "test-53c9555b06059",
  "time_start": "1450000000",
  "time_end": "1450700000",
  "traffic": [
    "install"
  ],
  "time_zone": "Asia/Seoul",
  "delivery_method": [
    "S3link"
  ],
  "delivery_format": "csv",
  "notify": [
    "test@kochava.com"
  ],
  "columns_order": [
    "install_matched_on",
    "install_matched_by",
    "install_status",
    "install_impression_date_utc",
    "install_impression_date_adjusted",
    "install_click_date_utc",
    "install_click_date_adjusted",
    "install_date_utc",
    "install_date_adjusted",
    "kochava_click_id",
    "partner_click_id",
    "click_network",
    "click_network_name",
    "click_country_code",
    "click_identifiers_email_0",
    "click_identifiers_email_1",
    "clickgeo_country_name",
    "impression_network",
    "impression_network_name",
    "impression_country_code",
    "installgeo_region",
    "installgeo_city"
  ]
}

 

Successful Response Example:

{
  "status": "queued",
  "report_token": "122245554"
}

 

Error Response Example:

{
  "status": "Error",
  "error": "Error request parameters app_guid missing."
}

Requesting a Detail Report Designed through the User Interface

Using this method will return a report with the specified columns as designed within the User Interface.

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/detail

 

Sample Post Body:

{
  "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
  "app_guid": "test-53c9555b06059",
  "time_start": "1450000000",
  "time_end": "1450700000",
  "traffic": [
    "event"
  ],
  "time_zone": "Asia/Seoul",
  "delivery_method": [
    "S3link"
  ],
  "delivery_format": "csv",
  "notify": [
    "test@kochava.com"
  ],
  "columns_order": [
    "default"
  ],
  "traffic_filtering": {
    "event_name": [
      "eCommerce - ViewDetail",
      "eCommerce - AddToCart"
    ]
  }
}

 

Successful Response Example:

{
  "status": "queued",
  "report_token": "122245554"
}

 

Error Response Example:

{
  "status": "Error",
  "error": "Error request parameters app_guid missing."
}

Obtaining a Report Status

Once a report has been successfully submitted, the status of the report can be obtained through an API call.

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/progress

 

Sample Post Body:

{
        "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
        "app_guid": "test-53c9555b06059",
	"token": "-5079248175472211673"
}

 

Successful Response Example:

{
  "status": "queued",
  "status_date": "2015-12-22 19:09:05",
  "progress": "0",
  "report_request": "..."
}

 

Error Response Examples:

{
    "status": "error",
    "status_detail": "Internal error"
  },
*An unexpected error occurred while running the report, trying again may resolve the issue.*  
{
    "status": "error",
    "status_detail": "Notification failed"
  },
*The notification for the report failed to be sent, but the report is otherwise valid and complete.*
 
{
    "status": "error",
    "status_detail": "APP & API Key are invalid"
  },
*The API key in the request is not valid for the App*
 
{
    "status": "error",
    "status_detail": "Cardinality for timeframe exceeded"
  },
*The report grouping chosen for the time frame is to large, you will need to update the API call to a smaller time frame.*

{
    "status": "error",
    "status_detail": "Error uploading to S3"
  },
*Uploading the completed report to S3 failed, the report must be run again.*
 
{
    "status": "error",
    "status_detail": "Row limit exceeded"
  }
*Row limit has been exceeded*

Delete a Queued Report

While a report is queued, it may be deleted. Once the report has run or is running, the operation cannot be canceled.

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/delete

 

Sample Post Data:

{
        "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
        "app_guid": "test-53c9555b06059",
	"token": "-5079248175472211673"
}

 

Successful Response Example:

{
	"status": "deleted"
}

 

Error Response Example:

{
	"status": "Error",
	“error”: “Error the report is not in a state that can be canceled”
}

Request a List of Apps by API Key

It is possible to view a list of the apps that are associated with a specific API key.

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/getapps

 

Sample Post Data:

{
       "api_key": "400f1cb412b444288e66e6f1d285b40c95rrre54"
}

 

Successful Response Example:

{
    [
        {
            "status":"OK",
            "guid":"kochavademoapp1455512d3024b2d5c",
            "app_name":"Kochava Demo App1",
            "app_id":"444",
            "account_name":"KochavaDemo {eeec3f678}",
            "platform": "android"
        },
        {
            "status":"OK",
            "guid":"kochavademoapp1469777d2872067cf",
            "app_name":"Kochava Demo App2",
            "app_id":"445",
            "account_name":"KochavaDemo {eeec3f678}"
            "platform": "ios"
        }
    ]
}

 

Error Response Example:

[
 {
   "status": "Error"
 }
]

Reports Generated by API Key

It is possible to view the last reports submitted by a specific account (App GUID).

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/tokens

 

Sample Post Data:

{
        "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
        "app_guid": "test-53c9555b06059",,
	"max_tokens": 2
}

 

Successful Response Example:

[{
	"status": "completed",
	"report_token": "-5079248175472211673",
	"status_date": "2016-03-04 18:42:24",
	"progress": "100",
	"report": "http://kochava-reporting.s3.yoururl.com/KRD-7921767224785405022_1511_kokochavabingodemo1347526e855c56f14.event_name.2016040600-2016040600.csv?AWSAccessKeyId=AKIAJ4JWD2ONNEYVOG4A&Expires=1460851374&Signature=vcn8QrmLq%2FyWf9PTfCkubWsOdag%3D",
	"report_type": "summary"
}, {
	"status": "completed",
	"report_token": "-5079248111473211673",
	"status_date": "2016-03-04 18:42:24",
	"progress": "100",
	"report": "http://kochava-reporting.s3.yoururl.com/KRS-4441768114781750949_192_kokochavabingodemo1347526e855c56f14.event_name.2016040600-2016040600.csv?AWSAccessKeyId=AKIAJ4JWD2ONNEYVOG4A&Expires=1460851374&Signature=vcn8QrmLq%2FyWf9PTfCkubWsOdag%3D",
	"report_type": "summary"
}]

Scheduling Reports Overview

Reports can be scheduled to run repeatedly as needed on a hourly, daily, weekly, monthly or quarterly basis. The start date and end date need to be calculated for every report that is run.

 

The following fields will assist in the scheduling:

 

Field Description
runon Defines when the report will run.
delay The value used to calculate the end date of the report from the runon time.
previoustime The difference between the start and end time.

 

Frequency RunOn Delay PreviousTime* Description
hourly Min
0
0
35
15
45		 Min
0
30
5
15
15		 Min
60
30
30
120
60		 on the hour for the previous 60 min
on the hour for the first 30 min of previous hour
at 35 past the hour for the first 30 min of the day
at 15 past the hour for the previous 2 full hours
at 45 past each hour, for 60 min (hour -1 :30 to hour:30)
daily Hour
0
13
2		 Hour
0
1
2		 Hour
24
24
48		 Start @ 0:00 for the past full day (24 hours)
Start @ 1:00 PM for the past 24 hrs (day -1 12:00 PM to 12:00PM)
Start @ 2:00 for the past full 2 days >=day-2@00:00 and < day:00:00(48 hours)
weekly dayID
1
1
6
1		 Day
0
1
0
0		 Day
7
7
5
2		 Start on Monday @ 0:00 for the previous week (Mon->Sund)
Start on Monday @ 0:00 for the previous week (Sund->Sat)
Start on Saturday @ 0:00 for the previous weekday (Mon->Frid)
Start on Monday @ 0:00 for the previous weekend (Sat,Sund)
monthly dayDate
1
15
16
1		 Day
0
14
0
0		 Month
1
2
2
6		 Run on the 1st of the month @ 0:00 for the entire previous month.
Run on the 15th of the month @ 0:00 for the previous 2 months
Run on the 16th for the previous month and 1/2 (1st of month -1 to 15 of current month)
Run on the 1st of the month @ 0:00 for the previous 6 months.

*The unit for “previous time” is different for each frequency because an hour/day/week is fixed. Month and Quarter are not fixed.

 

API Structures:

The structure for APIs are similar to the structures listed in the API Reporting Structure Section, with the following differences:

Parameter Difference Description Format Valid in Report Req.
time_start Removed – – – –
time_end Removed –  – – –
frequency Added How often the report should run (hourly, daily, weekly, monthly or quarterly). string Summary
Detail
Custom		 Yes
run_on Added When the report should run (on the x day, hour, minute, etc.). string Summary
Detail
Custom		 Yes
previous_time Added What period of time is included in the report. string Summary
Detail
Custom		 Yes
delay Added What is the end date of the report, based on when it ran. string Summary
Detail
Custom		 Yes

Schedule a New Summary Report

Post Endpoint:

https://reporting.api.kochava.com/v1.3/schedule/summary

 

Sample Post Data:

{    
    "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
    "app_guid": "test-53c9555b06059",
    "traffic":      ["click", "install","event"],
    "traffic_grouping": ["country"],
    "time_series": "24",
    "traffic_filtering": {
        "country": ["us","ca","mx"]
    },
    "delivery_format": "csv",
    "delivery_method": ["S3link"],
    "notify":   ["vprevost@kochava.com"],
    "frequency": "weekly",
    "run_on": "3",
    "delay": "2",
    "previous_time": "2"}
}

 

Successful Response Example:

{
  "status": "scheduled",
  "report_token": "122245554"
}

Schedule a New Detail Report

Post Endpoint:

https://reporting.api.kochava.com/v1.3/schedule/detail

 

Sample Post Data:

{
  "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
  "app_guid": "test-53c9555b06059",
  "traffic": [
    "install"
  ],
  "traffic_filtering": {
    "country": [
      "us",
      "ca",
      "mx"
    ]
  },
  "traffic_including": [
    "attribution"
  ],
  "delivery_format": "csv",
  "delivery_method": [
    "S3link"
  ],
  "notify": [
    "test@kochava.com"
  ],
  "frequency": "weekly",
  "run_on": "3",
  "delay": "2",
  "previous_time": "2"
}

 

Successful Response Example:

{
  "status": "scheduled",
  "report_token": "122245554"
}

Schedule a New Detail Report with Selected Columns

This call enables a Detail Report to be generated with a list of selected columns in the desired order.

 

NOTE: A default may be created and saved with the UI and called using the value “column_order”: [“default”].

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/schedule/detail

 

Sample Post Data:

{
  "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
  "app_guid": "test-53c9555b06059",
  "traffic": [
    "install"
  ],
  "traffic_filtering": {
    "country": [
      "us",
      "ca",
      "mx"
    ]
  },
  "traffic_including": [
    "attribution"
  ],
  "delivery_format": "csv",
  "delivery_method": [
    "S3link"
  ],
  "notify": [
    "test@kochava.com"
  ],
  "frequency": "weekly",
  "run_on": "3",
  "delay": "2",
  "previous_time": "2",
  "columns_order": [
    "install_matched_on",
    "install_matched_by",
    "install_status",
    "install_date_adjusted",
    "partner_click_id",
    "click_network_name",
    "installgeo_region",
    "installgeo_city"
  ]
}

 

Successful Response Example:

{
  "status": "scheduled",
  "report_token": "122245554"
}

Obtain the Status of a Scheduled Report

Post Endpoint:

https://reporting.api.kochava.com/v1.3/schedule/progress

 

Sample Post Data:

{
    "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
    "app_guid": "test-53c9555b06059", 
    "token":  "-6794248360722328501"}
}

 

Successful Response Example:

{
  "status": "scheduled",
  "status_date": "2016-03-01 01:54:20",
  "next_scheduled_on": "2016-04-01 00:00:00",
  "last_requested_token": "-1",
  "report_type": "summary",
  "report_request": {
    "API_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
    "app_guid": "test-53c9555b06059",
    "traffic": [
      "click"
    ],
    "traffic_grouping": [
      "country"
    ],
    "time_series": "24",
    "delivery_format": "csv",
    "delivery_method": [
      "S3link"
    ],
    "notify": [
      "test@kochava.com"
    ],
    "frequency": "monthly",
    "run_on": "2",
    "delay": "1",
    "previous_time": "1"
  }
}

 

Error Response Examples:

{
    "status": "error",
    "status_detail": "Internal error"
  },
*An unexpected error occurred while running the report, trying again may resolve the issue.*  
{
    "status": "error",
    "status_detail": "Notification failed"
  },
*The notification for the report failed to be sent, but the report is otherwise valid and complete.*
 
{
    "status": "error",
    "status_detail": "APP & API Key are invalid"
  },
*The API key in the request is not valid for the App*
 
{
    "status": "error",
    "status_detail": "Cardinality for timeframe exceeded"
  },
*The report grouping chosen for the time frame is to large, you will need to update the API call to a smaller time frame.*

{
    "status": "error",
    "status_detail": "Error uploading to S3"
  },
*Uploading the completed report to S3 failed, the report must be run again.*
 
{
    "status": "error",
    "status_detail": "Row limit exceeded"
  }
*Row limit has been exceeded*

Deleting a Scheduled Report

Post Endpoint:

https://reporting.api.kochava.com/v1.3/schedule/delete

 

Sample Post Data:

{
  "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
  "app_guid": "test-53c9555b06059",
  "token": "-6794248360722328501"
}

 

Successful Response Example:

{
  "status": "Deleted"
}

Scheduled Reports Generated by API Key

It is possible to view the last reports submitted by a specific account (API key).

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/schedule/tokens

 

Sample Post Data:

{ 
  "api_key": "4449A6AD-4CFB-439B-9B31-EBBB73A777BD",
  "app_guid": "test-53c9555b06059",
  "max_tokens": 2
}

 

Successful Response Example:

[
  {
    "status": "scheduled",
    "report_token": "7108991807226707174",
    "status_date": "2016-03-01 01:54:20",
    "next_scheduled_on": "2016-04-01 00:00:00",
    "report_type": "summary",
    "frequency": "monthly",
    "run_on": "1"
  },
  {
    "status": "scheduled",
    "report_token": "2086494630623150679",
    "status_date": "2016-03-01 01:12:23",
    "next_scheduled_on": "2016-04-01 00:00:00",
    "report_type": "summary",
    "frequency": "weekly",
    "run_on": "3"
  }
]

 
 

Last Modified: May 23, 2022 at 12:57 pm