# Reports

Over time we got a lot of requests for different kinds of reports. We had to collect the data manually, this cost both you and us time.

That's why we implemented a very flexible, yet simple system for reports. You can configure them with our web frontend and with our API.

This document is focused on the usage of the API endpoints, specifically for reporting purposes.

# Description

At first some explanation of how the reporting system works.

With this API you will be able to create Report Jobs, fetch and download Reports.

While the latter is the actual document with the data you wish to receive, Report Jobs is the configuration object that tells our system how to structure the reports and how often you want to receive them.

In other words, you tell us what kind of report you want with a Report Job configuration object and we will create the Reports and send them to you.

# One Time Reports and Recurring Reports

With schedule you can decide how often you want to receive a report, but this will also define the date range.

For example, daily reports are sent at the beginning of each day and include the data from the previous day. The same goes for weekly (every Monday for the previous week) and monthly (every 1st day of the month for the previous month).

Keep in mind that your number of active and paused recurring reports (Report Jobs) is limited to 15 per account. If you want to create more, you will have to archive one of the existing Report Jobs.

But what if you want more reports or configure a custom date range?

In this case you can create One Time Reports with "schedule": "once". You may create as many One Time Reports as you like, and you can select the date ranges for them manually.

# Detailed Campaign Reports and All Campaign Reports

Sometimes you may want a detailed look at a campaign and sometimes you may want a complete overview.

To make this possible there are two configuration options available: campaign_id and cluster_by.

For Detailed Campaign Reports you set campaign_id and set cluster_by to whatever option you like.

But if you want a Report with all your Campaigns, you will have to omit campaign_id and set cluster_by to campaign_id. The report will contain all Campaigns that received traffic during the time range.

# Report Jobs

Property Type Description Values Constraints Example
name String Name of the report Daily-Fruit-Report
status String Report Job status active, paused Default: active 50250fef9994650020000006
schedule String Interval how often you want to receive a report daily, weekly, monthly, once once requires from and to daily
parameters Report Job Parameters Report Structure configuration
emails Array of Emails Email addresses you want to send the report to Any email address that you added to your account Emails that are not registered in your account will be dropped
from Date One Time Report Start Only valid and required if schedule is once 2019-05-31 00:00:00
to Date One Time report End Only valid and required if schedule is once 2019-06-10 23:59:59

# Report Job Parameters

Property Type Description Values Example
cluster_by String Value you want to cluster by. ts is the timestamp device, browser, ts, source_id, os, carrier device
interval String Measure interval days, hours Default: days days
campaign_id String Campaign ID, if you want a detailed report of one campaign
source_id String or Array Filter by Source ID Any Source ID
device_type String or Array Filter by Device Type desktop, tablet, mobile desktop
os String or Array Filter by Operating System android, blackberry, macintosh, ios, windows, mobile_others, desktop_others, others android
browser String or Array Filter by Browser firefox, safari, opera, internet_explorer, others, chrome [ firefox, chrome ]

# Create Report Jobs

URL : /reportjobs

Method : POST

Response-Type: The created Report Job

# Recurring Report for all Campaigns

If you want to create a report for all campaigns you have to omit the campaign_id filter and set cluster_by to campaign_id.

Request

{
	"name": "weekly-all-campaigns",
	"schedule": "weekly",
	"parameters": {
		"cluster_by": "campaign_id",
		"interval": "days",
		"browser": "chrome"
	},
	"emails": ["your.account@email-address.com"]
}

Response

{
	"id": 99,
	"user_id": "youruserid",
	"name": "weekly-all-campaigns",
	"schedule": "weekly",
	"parameters": {
		"cluster_by": "campaign_id",
		"interval": "days",
		"browser": "chrome"
	},
	"emails": ["your.account@email-address.com"]
}

# Recurring Campaign Report

If you create a campaign report, you can choose every cluster_by option.

Request

{
	"name": "monthly-sweets-report",
	"schedule": "monthly",
	"parameters": {
		"campaign_id": "12345678901234567890asdf",
		"cluster_by": "browser",
		"interval": "hours",
		"source_id": [
			"123456789012345678901234",
			"abcdefghijklmnopqrstuvwx"
		]
	},
	"emails": ["your.account@email-address.com"]
}

Response

{
	"id": 100,
	"user_id": "youruserid",
	"name": "monthly-sweets-report",
	"schedule": "monthly",
	"parameters": {
		"campaign_id": "12345678901234567890asdf",
		"cluster_by": "browser",
		"interval": "hours",
		"source_id": [
			"123456789012345678901234",
			"abcdefghijklmnopqrstuvwx"
		]
	},
	"emails": ["your.account@email-address.com"]
}

# One Time Report

For One Time Reports you will have to set from and to.

Request

{
	"name": "one-time-sweets-report",
	"schedule": "once",
	"parameters": {
		"campaign_id": "12345678901234567890asdf",
		"cluster_by": "campaign_id",
		"interval": "days"
	},
	"from": "2019-03-13 00:00:00",
	"to": "2019-12-24 23:59:59",
	"emails": ["your.account@email-address.com"]
}

Response

{
	"id": 101,
	"name": "one-time-sweets-report",
	"schedule": "once",
	"parameters": {
		"campaign_id": "12345678901234567890asdf",
		"cluster_by": "campaign_id",
		"interval": "days"
	},
	"from": "2019-03-13 00:00:00",
	"to": "2019-12-24 23:59:59",
	"emails": ["your.account@email-address.com"]
}

# List Report Jobs

Returns a list with all Report Jobs of a user:

URL : /reportjobs

Method : GET

Response-Type: List of shortened Report Job Objects

Request example

GET https://api.advertiser.tonic.com/v1/reportjobs

Result example

[
	{
		"id": 1,
		"name": "Daily-Fruit-Report",
		"status": "active",
		"schedule": "daily",
		"interval": "days",
		"cluster_by": "ts",
		"campaign_id": "123456789012345678901234"
	},
	{
		"id": 2,
		"name": "Weekly-Fruit-Report",
		"status": "paused",
		"schedule": "weekly",
		"interval": "days",
		"cluster_by": "device"
	},
	{
		"id": 3,
		"name": "One-Time-Fruit-Report",
		"status": "active",
		"schedule": "once",
		"interval": "hours",
		"cluster_by": "ts",
		"from": "2019-05-31 02:00:00",
		"to": "2019-05-31 14:00:00"
	}
]

# Get a Report Job

Returns a Report Job with all its parameters:

URL : /reportjobs/:id

Method : GET

Response-Type: Report Job Object

Request example

GET https://api.advertiser.tonic.com/v1/reportjobs/1

Result example

{
	"id": 1,
	"name": "Daily-Fruit-Report",
	"status": "active",
	"schedule": "daily",
	"parameters": {
		"interval": "days",
		"cluster_by": "ts",
		"campaign_id": "123456789012345678901234",
		"device_type": ["desktop", "tablet"],
		"os": ["windows", "macintosh", "ios"],
		"browser": ["safari", "firefox"]
	},
	"email": ["account@email-address.com"]
}

# Get a list of Reports

Returns a list of Reports including their metadata. You can download the report document with the downloadUrl.

URL : /reportjobs/:id/reports

Method : GET

Response-Type: List of Report Objects

Request example

GET https://api.advertiser.tonic.com/v1/reportjobs/1/reports

Result example

[
	{
		"id": 1,
		"status": "done",
		"start_date": "2019-05-01 00:00:00",
		"end_date": "2019-05-01 23:59:59",
		"created_at": "2019-05-02 00:00:00",
		"changed_at": null,
		"downloadUrl": "https://api.advertiser.tonic.com/v1/reportjobs/1/reports/1/download?token=aoqwef09233e123asdlkj209"
	},
	{
		"id": 2,
		"status": "done",
		"start_date": "2019-05-02 00:00:00",
		"end_date": "2019-05-02 23:59:59",
		"created_at": "2019-05-03 00:00:00",
		"changed_at": null,
		"downloadUrl": "https://api.advertiser.tonic.com/v1/reportjobs/1/reports/2/download?token=320923klasdfas09230912"
	},
	{
		"id": 3,
		"status": "planned",
		"start_date": "2019-05-03 00:00:00",
		"end_date": "2019-05-03 23:59:59",
		"created_at": "2019-05-04 00:00:00",
		"changed_at": null,
		"downloadUrl": "https://api.advertiser.tonic.com/v1/reportjobs/1/reports/3/download?token=asfdlksdgfoirtasd092309caslksasdf"
	}
]

# Get one Report

Returns metadata of a Report. You can download the report document with the downloadUrl.

URL : /reportjobs/:id/reports/:reportId

Method : GET

Response-Type: Report Object

Request example

GET https://api.advertiser.tonic.com/v1/reportjobs/1/reports/1

Result example

{
	"id": 1,
	"status": "done",
	"start_date": "2019-05-01 00:00:00",
	"end_date": "2019-05-01 23:59:59",
	"created_at": "2019-05-02 00:00:00",
	"changed_at": null,
	"downloadUrl": "https://api.advertiser.tonic.com/v1/reportjobs/1/reports/1/download?token=aoqwef09233e123asdlkj209"
}

# Download a Report Document

Redirects to the downloadable report document. You can only download a report if its status is done.

URL : /reportjobs/:id/reports/:reportId/download

Method : GET

Response-Type: Report Object

Request example

GET https://api.advertiser.tonic.com/v1/reportjobs/1/reports/1/download?token=aoqwef09233e123asdlkj209

# Archive a Report Job

If a Report Job is no longer necessary, you can archive it.

You can still download the reports but you will no longer be able to let this Report Job run.

URL : /reportjobs/:id

Method : DELETE

Response-Type: -

Request example

DELETE https://api.advertiser.tonic.com/v1/reportjobs/1
Last Updated: 5/26/2021, 1:43:45 PM