API v1.4 – Requesting and Scheduling Reports

Feature Summary: The Kochava 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.4 has been divided into the following sections:

Call Structure
Querying API
Requesting and Scheduling Reports

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.

NOTE: Kochava’s API also provides the ability to schedule custom query reports.
https://reporting.api.kochava.com/v1.4/schedule/custom
For information on the proper format, contact your Customer Success Management Team.

WARNING: If the provided API Key does not match an existing app, an “error”:”App does not exist.” response will be returned. For further information, contact your Client Success Management team.

CAUTION: If a request is sent that is a duplicate of another report currently queued or running, no token will be returned. The response will be returned with a status of “queued” or “running” for the duplicate report that was requested.

NOTE: There are several sources of Restricted data you will see across views in Query, Reporting and Analytics. This is data the media channel prohibits Kochava from sharing at the row level, but you will find the channel information contained in your summary reporting. Please reach out to your Kochava Client Success Management Team for more information.

Report Download Options

Kochava S3 and a Customer S3 Bucket:

Kochava S3 provides a link to download the report [“S3link”].
Customer S3 bucket using values such as [“S3bucket”, “region”, “bucketname”, “accessKey”, “SecretKey”]. If only [“S3bucket”] is provided, the system will try to retrieve the credentials that have been saved for that app. If none are found, a link to download the report from our S3 bucket will be provided.

NOTE: A download link will only be sent to the SFTP bucket and would not be provided in the confirmation email.

Sample Post of Report Sent to a Customer’s S3 Bucket —

{
  "api_key": "AAA9A6AD-4CFB-439B-9B31-EBBB73A199BD",
  "app_guid": "koyahoo-android5559699b06059",
  "time_start": "1450000000",
  "time_end": "1450700000",
  "traffic": [
    "click"
  ],
  "traffic_grouping": [
    "country"
  ],
  "time_series": "1",
  "time_zone": "America/Toronto",
  "traffic_filtering": {
    "network": [
      "120",
      "550"
    ],
    "country": [
      "us",
      "ca",
      "mx"
    ]
  },
  "delivery_method": [
    "S3bucket",
    "us-west-2",
    "reportfromKochava",
    "BBBSHHHFTTYTHDHDHHDTGGBS/JHTS54",
    "BBBSHHHFTTYTHDHDHHDTG?POLKJ8674FT"
  ],
  "delivery_format": "csv",
  "notify": [
    "email@yourdomain.com"
  ]
}

In order to use your S3 Bucket to receive a report, the following permissions are required on the bucket for the credentials that you are providing:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::bucket-name/*"
        }
    ]
}

SFTP:

SFTP delivery method is only available with version 1.4 of the Reporting API.

Sample Post of Report Sent to SFTP —

{
  "api_key": "AAA9A6AD-4CFB-439B-9B31-EBBB73A199BD",
  "app_guid": "koyahoo-android5559699b06059",
  "time_start": "1450000000",
  "time_end": "1450700000",
  "traffic": [
    "click"
  ],
  "traffic_grouping": [
    "country"
  ],
  "time_series": "1",
  "time_zone": "America/Toronto",
  "traffic_filtering": {
    "network": [
      "120",
      "550"
    ],
    "country": [
      "us",
      "ca",
      "mx"
    ]
  },
 "delivery_method": [
  "SFTP",
  "{ip address}",
  "{port}",
  "{user name}"
 ],
  "delivery_format": "csv",
  "notify": [
    "email@yourdomain.com"
  ]
}

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.

Time_zone must be UTC and start at the beginning of the day.
Time_series must be set to 24.
Traffic grouping must include “network”.

Clicks Counters:

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

Installs Counters:

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

SKAdNetwork Counters:

# skadnetwork
# skadnetwork matched to impressions
# skadnetwork matched to clicks

Impression Counters:

# impressions
Amount spent on Impression

Reengagement Counters:

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

CAUTION: The time_start and time_end parameters must be in Unix seconds. Kochava will drop any report that does not have time_start and time_end in seconds and return an error stating “time_start or time_end was not in seconds.”

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/summary

Sample Post Data:

{
  "api_key": "ADD_API_KEY_HERE",
  "app_guid": "YOUR_APP_GUID",
  "columns_order": [
    "all"
  ],
  "custom_report_name": "kochavaquery",
  "delivery_format": "csv",
  "delivery_method": [
    "S3link"
  ],
  "delivery_receipt": "estimated_install_date",
  "notify": [
    "yourname@email.com"
  ],
  "report_name": "SKAdNetworkInstallReport",
  "template_name": "SKAdNetwork Install",
  "time_end": "1607644799",
  "time_start": "1606867201",
  "time_series": "1",
  "time_zone": "UTC",
  "traffic": [
    "install",
    "skadnetwork"
  ],
  "traffic_grouping": [
    "date_range_utc",
    "ko_account_name",
    "ko_account_id",
    "advertiser_app_store_id",
    "ko_app_name",
    "ko_app_id",
    "ko_app_guid",
    "sk_ad_network_id",
    "ko_media_partner_name",
    "ko_media_partner_id",
    "sk_campaign_id",
    "campaign_name"
  ]
}

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, reengagement_imp, influencer_imp, influencer_click, collected cost, fractional, and cost v2.

NOTE: Cost v1 has been sunsetted. Data for this report will only be pulled through 03/30/2022. For more information about using Cost v2, please contact your Client Success Manager.

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/Reengagement – 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: 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.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/detail

Sample Post Data:

{
  "api_key": "YOUR_API_KEY",
  "app_guid": "YOUR_APP_GUID",
  "delivery_format": "csv",
  "delivery_method": [
    "S3link"
  ],
  "event_name": [
    "eCommerce - ViewDetail",
    "eCommerce - AddToCart"
  ],
  "notify": [
    "yourname@email.com"
  ],
  "time_end": "1607644799",
  "time_start": "1606867201",
  "time_zone": "Asia/Seoul",
  "traffic": [
    "event"
  ],
  "traffic_filtering": {
    "exclude_network": [
      "499"
    ]
  }
}
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.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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": [
    "email@yourdomain.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.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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": [
    "email@yourdomain.com"
  ],
  "columns_order": [
    "default"
  ]
}

Successful Response Example:

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

Error Response Example:

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

Request a New Kochava Query Report

Call with the following JSON structure:

NOTE: In order for the report to run properly, the custom_report_name must remain as kochavaquery.

NOTE: In order to run a query in Standard SQL, include the following in the POST body:
“use_standard_sql”: true

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/custom

Sample Post Body:

{
  "api_key": "XXXXX",
  "app_guid": "jd-test-app-XXXXXX",
  "custom_report_name": "kochavaquery", /* The custom_report_name must remain as kochavaquery in order for the report to run. */
  "notify": [
    "XXXX@kochava.com"
  ],
  "sql_kquery": "select * from installs_primary where date(date_occurred) between '2019-08-01' and '2019-08-08'",
  "time_start": "1561876200",
  "time_end": "1561877999",
  "delivery_format": "csv",
  "use_standard_sql": true
}

Sample Response:

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

Request a New Audience Export

A request to generate a report for audience export (devices). This request is based on a filter from Analytics. This can be passed under ‘analytics’ field or by just the id on ‘filter_set_id’.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/deviceid

Sample Post Body:

{
    "app_guid": "koboss-land-android-tewdf",
    "api_key": "00000000-0000-0000-0000-000000000000",
    "report_name": "Test Audience Export",
    "delivery_format": "csv",
    "time_start": "1450000000", 
    "time_end": "1450700000", 
    "delivery_method": [
        "S3link"
    ],
    "traffic_filtering": [
        "timerange": ["month to date"]
    ],
    "filter_set_id": "276712",
    "activation_partner_id": "13",
    "analytics": {
        "filters": [
            {
                "dimension": "app_id",
                "modifier": "in",
                "logic": "and",
                "values": [
                    "26538"
                ]
            },
            {
                "dimension": "attribution_network",
                "modifier": "in",
                "logic": "and",
                "values": [
                    "Kochava Soltest - General"
                ]
            }
        ]
    }
}

Sample Response:

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

Request a New Audience Activation

A request to generate an Audience Activation. This is similar to Audience Export, but instead of delivering the Audience to the user, the Audience is delivered directly to the Partner. This request is based on a filter from Analytics or a custom query.

NOTE: filter_set_id or sql_kquery is required. See Filter Sets Endpoint[add link] documentation for how to access the ID’s of Filter Sets.

NOTE: time_start and time_end are not required and will be ignore if sql_kquery is present.

NOTE: ad_account_id can be passed to maintain the specified account in case the credentials would have changed (if applicable to the Activation Partner).

NOTE: notify can be provided to send an email to the listed addresses on success/failure.

NOTE: report_name is used as the audience name with the partner where applicable.

NOTE: partner_audience_id can be passed to specify a specific audience to activate to (if applicable). Usually this is generated when creating the audience for the first time.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/audience

Sample Post Body:

{
  "app_guid": "koboss-land-android-tewdf",
  "api_key": "00000000-0000-0000-0000-000000000000",
  "report_name": "Facebook - My Audience - 1540250385",
  "time_start": "1538352000",
  "time_end": "1539129600",
  "filter_set_id": "9776",
  "sql_kquery": "SELECT 'adid' as device_id_type, adid FROM app_26538.events_primary WHERE date_occurred >= \"2018-10-01\" AND adid IS NOT NULL",
  "activation_partner_id": "13",
  "partner_audience_id": "103478178340",
  "delivery_format": "csv",
  "notify": [
    "someone@kochava.com"
  ],
  "credentials": {
    "ad_account_id": "1234"
  }
}

Sample Response:

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

Obtaining a Report Status

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

A report can be in one of the three status states:

Queued
In Progress
Completed

When the report has completed, this response will include the S3 link to download the report.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/progress

Sample Post Body:

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

Successful Response Example:

{
    "status": "completed",
    "status_detail": "completed",
    "status_date": "2018-08-29 16:57:22",
    "progress": "100",
    "file_size": 3236,
    "report": "http://kochava-reporting.s3.amazonaws.com/KR9994975629471553637_34289635_koclienttest-3g68irxyl.install_201712010000-201712012359-TZ_UTC.csv?AWSAccessKeyId=AKIAJ4JWD2OCXDYVOG4A&Expires=1536425842&Signature=erknlPYDzZs9VozFXJnHlAQFCgk%3D",
    "report_type": "detail",
    "report_request": {
        "api_key": "4449C969-46C3-0F8A-6C26-DA25CAC44021",
        "app_guid": "koclienttest-3g68irxyl",
        "time_start": "1512086400",
        "time_end": "1512172799",
        "traffic": [
            "install"
        ],
        "traffic_including": [
            "unattributed_traffic"
        ],
        "time_zone": "UTC",
        "delivery_format": "csv",
        "delivery_method": [
            "S3link"
        ],
        "notify": [
            "email@yourdomain.com"
        ]
    }
}

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.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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).

Endpoint:

GET https://reporting.api.kochava.com/v1.4/tokens

NOTE: This call will return scheduled report tokens for reports scheduled by the API key used, rather than scheduled by the user. Reports scheduled via the UI are created using the user’s first API key.

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

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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":   ["email@yourdomain.com"],
    "frequency": "weekly",
    "run_on": "3",
    "delay": "2",
    "previous_time": "2"}
}

Successful Response Example:

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

Schedule a New Detail Report

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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": [
    "unattributed_traffic"
  ],
  "delivery_format": "csv",
  "delivery_method": [
    "S3link"
  ],
  "notify": [
    "email@yourdomain.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”].

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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": [
    "email@yourdomain.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"
}

Schedule an Audience Export Report

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/schedule/deviceid

Sample Post Body:

{
    "app_guid": "koboss-land-android-tewdf",
    "api_key": "00000000-0000-0000-0000-000000000000",
    "report_name": "Weekly Audience Export",
    "frequency": "weekly",
    "run_on": "1",
    "previous_time": "0",
    "delay": "7",
    "delivery_format": "csv",
    "delivery_method": [
        "S3link"
    ],
    "traffic_filtering": [
        "timerange": ["month to date"]
    ],
    "filter_set_id": "276712",
    "activation_partner_id": "13",
    "analytics": {
        "filters": [
            {
                "dimension": "app_id",
                "modifier": "in",
                "logic": "and",
                "values": [
                    "26538"
                ]
            },
            {
                "dimension": "attribution_network",
                "modifier": "in",
                "logic": "and",
                "values": [
                    "Kochava Soltest - General"
                ]
            }
        ]
    }
}

Successful Response Body:

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

Schedule an Audience Activation

A request to schedule an Audience Activation. This is similar to Audience Export, but instead of delivering the Audience to the user, the Audience is delivered directly to the Partner. This request is based on a filter from Analytics or a custom query.

NOTE: Either filter_set_id or sql_kquery is required.

NOTE: time_start and time_end are not required and will be ignore if sql_kquery is present.

NOTE: ad_account_id can be passed to maintain the specified account in case the credentials would have changed (if applicable to the Activation Partner).

NOTE: notify an be provided to send an email to the listed addresses on success/failure.

NOTE: report_name is used as the audience name with the partner where applicable.

NOTE: partner_audience_id can be passed to specify a specific audience to activate to (if applicable). Usually this is generated when creating the audience for the first time.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/schedule/audience

Sample Post Body:

{
  "app_guid": "koboss-land-android-tewdf",
  "api_key": "00000000-0000-0000-0000-000000000000",
  "report_name": "Facebook - My Audience - 1540250385",
  "frequency": "weekly",
  "run_on": "1",
  "previous_time": "0",
  "delay": "7",
  "filter_set_id": "9776",
  "sql_kquery": "SELECT 'adid' as device_id_type, adid FROM app_26538.events_primary WHERE date_occurred >= \"2018-10-01\" AND adid IS NOT NULL",
  "activation_partner_id": "13",
  "partner_audience_id": "103478178340",
  "delivery_format": "csv",
  "notify": [
    "someone@kochava.com"
  ],
  "credentials": {
    "ad_account_id": "1234"
  }
}

Successful Response Example:

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

Schedule a New Kochava Query Report

Call with the following json structure:

NOTE: In order to run a query in Standard SQL, include the following in the POST body:
“use_standard_sql”: true

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/schedule/custom

Sample Post Body:

{
    "api_key":     "ABC-XXX",
    "app_guid":      "AYZXYX",
    "custom_report_name": "kochavaquery",
    "notify":   ["email@yourdomain.com"],
    "sql_kquery": "SELECT clicks.network_id, clicks.date_received, ins_attr.date_received, click_prop.* FROM app_XXX.install_attribution as ins_attr join app_XXX.clicks as clicks on clicks.click_id = ins_attr.matched_to_id join app_XXX.click_properties as click_prop on click_prop.click_id = ins_attr.matched_to_id where  clicks.date_received BETWEEN DATE_ADD(CURRENT_TIMESTAMP(), -24, 'HOUR')  AND CURRENT_TIMESTAMP() order by ins_attr.date_received",
    "frequency": "daily",
    "run_on": "0",
    "use_standard_sql": true
}

Successful Response Example:

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

Obtain the Status of a Scheduled Report

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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": [
      "email@yourdomain.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*

Update the Distribution List of a Scheduled Report

The list of email that get notified when a report has run can be updated for a scheduled report (instead of deleting and re creating the scheduled report). The only field that CAN be updated as of now is the notify list.
If a token is present, the request is treated as an update. If no token, it is the usual add a scheduled report.

NOTE: The same API key and endpoint MUST be used to update the email list.

NOTE: If a /schedule/detail report is created, the update must be on /schedule/detail. If a /schedule/summary report is created, the update must be on /schedule/summary.

Endpoint:

POST: /schedule/detail or /schedule/summary or /schedule/custom

Sample Post Data:

        {
            "api_key":     "AAAAA6AD-4CFB-439B-9B31-EBBB73A199BD",
            "app_guid":      "koyahoo-android53c9699b06059",
            "token": "-1231410796831263",
            "notify":   ["email@yourdomain.com", "xyz@kochava.com", "abc@inc.ca"]
        }

Sample Post Response:

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

Deleting a Scheduled Report

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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 for a specific app using the below endpoint.

Endpoint:

POST: https://reporting.api.kochava.com/v1.4/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"
  }
]