Reporting

The Buzz UI and API include Report Builder, a full-featured reporting engine for aggregated data about campaign performance. Reports are requested asynchronously and may be saved and scheduled using the API.

📘

Migration Notes from 0.5 API

• The Report Builder 2.0 API is entirely different from the 0.5 report_queue API. The new API is more powerful and flexible than the previous version and should require fewer requests and overhead.
• The 0.5 API is no longer available and all customers should use the 2.0 API described here.

Initializing a Reporting Profile

Before the API can be used, it is required for every user to visit the Report Builder UI to initialize a Reporting Profile. For most users this process should only be required once or to receive access to new reports.

Syncing a Reporting Profile

If a user's Buzz Role changes which fields or reports the user has access to, the API user may fall out of sync with the Report Builder front-end. In such scenarios the API will error any subsequent requests to ensure the user has adequate permissions. To re-sync permissions in such a scenario the user needs to revisit Report Builder in the UI.

Getting a list of available reports and fields

To retrieve a list of available reports make a GET request to the /reporting/reports resource.

This will return a list of Reports by name, ID and view -- the view is important as it is used as an input into other queries. The list of reports will only include those permissioned to the user.

To retrieve a list of accessible fields in a Report, make a GET request to the /reporting/reports/{report_name} resource with the{report_name} replaced by the view. For example, Performance Report fields should be fetched at /reporting/reports/performance_agg.

The name field in the returned response should be used to specify the fields in a given report in subsequent requests.

Running ad hoc queries

To run queries, POST requests should be made to the /reporting/run-query endpoint. The general interface of the POST request is shown below, along with descriptions of the fields.

{
	"view": "performance_agg",
  "pivots": ["environment_type"],
	"fields": ["campaign_id","environment_type","impression"],
	"limit": 100,
	"filters": {
		"bid_day": "after 2019-01-01"
	},
	"result_format": "csv",
	"query_timezone": "America/New_York",
	"sorts": ["impression DESC", "campaign_id ASC"]
}

Upon successful post to the async query endpoint, the user will receive a response containing their task_id for future retrieval.

{
    "task_id": "d865ec8efa6c4a22dc07bc0ff79684d6",
    "message": "We are are processing your report. Make a GET request to http://canary.api.beeswax.com/rest/v2/reporting/async-query/d865ec8efa6c4a22dc07bc0ff79684d6 to check the report's status and retrieve the results of your query."
}

📘

Query Results Caching

Query Results are held in cache for approximately one hour after query completion; if results are not fetched within an hour they are dropped from cache and you will not be able to access your results.

Fetching a Report's Results

By making a GET request to the URL provided in the response of the POST request you can check the status and fetch the results of the query. The resource used is /reporting/async-results/{id}.

If the query is still processing the response code will be a 204. A completed query will return a 200 with the response containing the requested data.

Report results

For JSON reports, the results will be returned as an array of JSON objects where each object represents a row:

[{
		"Line Item ID": 1892,
		"Impressions": 75450
	},
	{
		"Line Item ID": 2363,
		"Impressions": 49859
	},
	{
		"Line Item ID": 2364,
		"Impressions": 49733
	}
]

Pivoted results will return will return the pivoted dimension nested in the JSON object for each "row" of data:

[
    {
        "Hour": "2020-06-30 23:00:00",
        "Line Item ID": 2724,
        "Impressions": {
            "Environment Type": {
                "APP": null,
                "WEB": 1835
            }
        }
    },
    {
        "Hour": "2020-06-30 22:00:00",
        "Line Item ID": 2724,
        "Impressions": {
            "Environment Type": {
                "APP": null,
                "WEB": 2231
            }
        }
    },
    {
        "Hour": "2020-06-30 22:00:00",
        "Line Item ID": 2731,
        "Impressions": {
            "Environment Type": {
                "APP": 1,
                "WEB": 1069
            }
        }
    }
]

Other reports will return the results in the requested file format.

Folders

In Report Builder users have two sets of “folders” they can save their reports. The first is their personal folder and the second is a folder shared with all users in the same Account. The IDs for these folders are used when saving reports and may be retrieved with a GET request to the /reporting/folders resource. Sample response:

{
	"count": 2,
	"next": null,
	"previous": null,
	"results": [{
			"id": "72",
			"name": "canary-17",
			"is_personal": false
		},
		{
			"id": "130",
			"name": "Harry Houdini",
			"is_personal": true
		}
	]
}

Saving reports

📘

Migration Notes from 0.5 API

• Reports saved in the 0.5 API are not automatically migrated to the 2.0 API, they must be recreated.

Creating a new saved report entails making a POST request to the /reporting/saved-reports resource. The request structure is similar to the ad hoc query described above, with a few additional available fields. Example shown below:

{
	"title": "My saved API example!",
	"description": "I'm a helpful description",
	"query": {
		"view": "geo_agg",
		"fields": [
			"geo_zip", "bid_hour", "inventory_source", "impression", "line_item_id"
		],
		"limit": 100,
		"filters": {
			"bid_day": "after 2020-06-01"
		},
		"sorts": ["bid_hour ASC"],
		"query_timezone": "Pacific/Auckland"
	},
	"folder_id": 72
}

A GET request can also be made to this endpoint to fetch a list of existing saved reports.

Running a saved report

To run an existing saved report, a POST request should be made to reporting/run-saved-report. A saved_report_id must be passed to specify which saved report to run. Two optional parameters that can be passed in this request, result_format and limit.

{
  "saved_report_id": 121
	"result_format": "csv",
	"limit": 10000
}

Once a saved report is run, its results are fetched in the same way as an ad hoc report: a task_id will be returned that can be used to fetch results from the /reporting/async-results/{id} endpoint.

Scheduling reports

You can schedule reports to run automatically and output in various ways. New reports are created by making a POST request to the reporting/report-schedules resource. The body of this endpoint looks like the following (this example includes instances of every possible Schedule Destination, but in practice all schedule destinations must be of the same type in the same schedule):

{
	"crontab": "0 15 * * *",
	"saved_report_id": 120,
	"name": "My Example Schedule",
	"scheduled_plan_destination": [{
			"format": "csv",
			"address": "[email protected]",
			"type": "email",
			"message": "Hello, world"
		},
		{
			"format": "json",
			"address": "s3://beeswax-tmp/",
			"type": "s3",
			"parameters": {
				"access_key_id": "access_key_here",
				"region": "us-east-1"
			},
			"secret_parameters": {
				"secret_access_key": "secret_key_here"
			}
		},
    {
    	"type": "sftp",
    	"format": "csv",
      "address": "sftp://example-sftp.com/file_path,
      "parameters": {
      	"username": "foo"
      },
      "secret_parameters": {
      	"password": "bar"
      }
    },
    {
    	"type": "webhook",
    	"format": "csv",
      "address": "https://example.com/webhook_uri"
    }
	],
	"send_all_results": false,
	"timezone": "America/New_York"
}

A GET request can also be made to this endpoint to fetch a list of existing schedules.

Running a scheduled report once

There are use cases where running a scheduled report one time is desirable. There are two supported workflows for this:

First, an existing scheduled report can be run a single time by making a POST request to /reporting/report-schedules/{id}/run-once. This can be useful for testing an existing schedule and making sure credentials and delivery parameters are setup correctly without needing to wait for the next scheduled run.

Second, a report that has no existing schedule can be run a single time by making a POST request to /reporting/report-schedules/run-once with a schedule_plan_destination and name fields in the body of the request. A crontab is not required. This can be useful for sending a one-time report to a destination such as S3 or email but does not need to be run on a recurring schedule.