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` (Required)Specifies the report to be queried.
`pivots`Pivots are an array of fields that can be optionally set. When set, pivots will distribute metrics horizontally with a column for the pivoting field, similar to a pivot table in a spreadsheet. For a field to be pivoted, it must be added to both the pivots array **and** the fields array specified below.
`fields` (Required)Fields can be either dimensions (qualitative, descriptive data used to group rows in reports -- for example, “Campaign Name” or “Environment Type”) or measures (quantitative metrics that are the actual numbers in a report -- for example, “Impressions” or “Spend”). Fields expects an array of strings that will be all the requested dimensions or measures in the report. Unlike the 0.5 API, you can put both “fields” and “metrics” in the same property of the API request.
`limit`This specifies the row limit in the report, the maximum accepted value is 30,000.
`filters`Accepts an object containing key/value pairs to filter, where the key specifies the field or metric and the value specifies the filtering condition. Multiple filters can be added by adding new key/value pairs to the object. NOTE: Filtering does not support the general API filtering described in [GET-ting Data from the API](🔗). If a `bid_day` filter is not specified a default filter set to “last 7 days” will be applied. See also: [Multi-Account Reporting](🔗) for filtering across Accounts.
`result_format`Specifies the file format of the response. Acceptable formats are: _ `json` (default) _ `csv` _ `xlsx` _ `txt` (tab-delimited) _ `png` _ `md` _ `html` _
`query_timezone`The timezone to run the query in, if different than the Account’s timezone. If unspecified the Account setting is used. The format should use tz syntax such as `Asia/Kuala_Lumpur`.
`sorts`An array of strings specifying the sort conditions of the report. The proper syntax for each string is `field_name ASC/DESC`.

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

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:

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

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:

## 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` (Required)A title for the Saved Report.
`description`Optional description.
`query` (Required)This specifies the query using the same syntax as the ad hoc query. Saved reports have an enforced limit of 5,000 rows. At run-time this limit can be overwritten.
`folder_id`This specifies the folder in which to save the saved report. If not specified, the report will be saved in the user’s personal folder.

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`The ID of Saved Report. This will be returned when a saved report is created or can be found by making a `GET` request to the `/saved-reports` endpoint.
`result_format`Optionally specify a result format to return the results. Saved Reports cannot be saved with a result format associated. Instead, the format is specified when the report is run.
`limit`Users can set a limit when running the saved report. This limit will override the row limit set on the saved report, and can exceed the 5,000 row limit set there to a maximum of 30,000 rows.

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` (Required)The crontab is the schedule for the report specified in Vixie Cron syntax. If you are unfamiliar with cron schedules you can play around with cron schedules [here](🔗). The first value in the cron schedule must be a single integer and cannot be a wildcard, step value or range of values. This ensures all schedules run at most once an hour.
`saved_report_id` (Required)The Saved Report you wish to schedule -- all schedules must use a previously existing saved report.
`name` (Required)A name for the schedule. This is used to define file names and subject lines for email-based delivery.
`scheduled_plan_destination`This object array holds the necessary parameters for the location to send the scheduled report. To send to multiple email addresses create an object for each email address. When sending to S3, only one destination may be specified. When setting a format in a scheduled report it is worth noting that the `format` parameters in the `scheduled_plan_destination` object are slightly different. For example, to receive a png of the visualization you will need to specify “inline_visualizations” instead. **Emailed Reports** Requires the email address and file format. Specify the `type` as `email.` An optional `message` property can be set that will be added to the body of the email. **S3 Reports** Will require the S3 bucket location and file format. Specify the `type` as `s3.` Additionally, to ensure proper permissions in S3 are enforced, the user must specify an Access Key and Secret Key of an IAM resource that has the ability to write to the S3 location specified. For security reasons, these keys will not be exposed in plaintext when fetching the report schedule information. **SFTP Reports** SFTP Reports will require an address of an SFTP server as well as a username and password with permissions to access the SFTP server. **Webhook Reports** Webhook reports require an address of an HTTPS URI which can receive webhooks.
`send_all_results`Set to `true` or `false`. If `false`, the report will send the specified row limit set on the saved report. If `true`, the schedule will send all the results specified by the query. This is the proper way to run a large report that would’ve previously required pagination.
`timezone`Timezone to run the report in -- this timezone also applies to the cron schedule of the report, so a schedule of `* 6 * * *` would run at 6AM EST if `America/New_York` is set as the timezone

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.