Welcome to Singular's Reporting API, which offers aggregated stats about your marketing campaigns that you can ingest into your internal BI systems or marketing performance dashboards.

This guide explains the Singular Reporting API, how to understand your use case, and how to start running queries.

Read this guide first, then review theReporting API Reference for the technical details.

 

Getting Started: Understanding Your Use Case

Singular gathers and synthesizes data from different origins (we recommend reading Understanding Singular Reporting Data for an in-depth review).

When you use the Reporting API, you can choose whether you want to see:

• Aggregated data from your partner ad networks and agencies, such as campaign cost;
• Aggregated data from your attribution tracker/MMP, which you can ingest into your BI system and join to network data as needed;
• Or combined data, which is the result of Singular's smart joining of network and tracker data to let you analyze your ROI in the highest possible granularity.

While all the queries are run through the same endpoint (Create Async Report), they differ in which fields you include in the query.

To get started, understand what you want to get from the API:

Your Use Case:	See:
You use Singular to collect campaign data from all your ad networks and agencies. You want to get data about your costs and run rates.	Querying Network Data
You use the Singular attribution service or have set up a data connector for your third-party attribution tracker. You want to pull tracker data such as conversions and revenue and ingest it into your BI platform or for analysis. If you do join the tracker data to ad network data (such as campaign cost) to calculate your ROAS, you plan to use your own tools to do so.	Querying Tracker Data and Network Data Separately
You use the Singular attribution service or have set up a data connector for your third-party attribution tracker. You want to take advantage of Singular's ready-made logic for joining network and tracker data with the highest possible granularity.	Querying Combined Data

The Types of Data Available Via the Reporting API

Querying Network Data

Network data includes campaign statistics ingested from all the ad networks you have set up in Singular. It does not include data from your attribution tracker (if you have set up any in Singular).

For example, you can run a query to see the cost (adn_cost) for each of your campaigns (adn_campaign_id) in a given date range.

Available Fields for Network Data

See the Metrics and Dimensions page for a description of each field.

Querying Tracker Data and Network Data Separately

You can use the API to pull tracker data - stats from Singular's attribution service or from a third-party attribution tracker you have set up in Singular (such as Appsflyer or Google Analytics).

For example, you can run a query to see the clicks (tracker_clicks) and installs (tracker_installs) for each of your campaigns (tracker_campaign_id) in a given date range. Tracker stats also include post-install events and revenue.

Having run a query on tracker data, you can join it to your network data to be able to calculate your campaign CPI or ROI.

However, running a combined report is usually an easier way to achieve the same result.

Available Fields for Tracker Data

See the Metrics and Dimensions page for a description of each field.

Querying Combined Data

You can use the API to run a combined network and tracker query, which displays both your campaign costs and your revenue or other campaign performance KPIs.

This type of query makes use of special dimensions and metrics that are based on tracker and network data but involve additional logic behind the scenes, as detailed below.

What does a combined query do?

1. It includes both network stats (such as cost) and tracker stats (such as installs and revenue) in the same query.

2. Smart dimensions help combine the network and tracker data into the same row wherever possible.

   Singular's "combined" or "unified" dimensions are based on both network and tracker data. They are processed by Singular to correct common data mismatches and make sure you see your combined data with the highest possible granularity.

   For example, the name of a specific campaign in the tracker may be slightly different from the name of the campaign as pulled from the ad network. So if you run a tracker report and a network report and join the results, you may get split rows for the campaign, where one row has network stats and the other has tracker stats. But if you run a combined report (using the unified_campaign_name dimension), Singular makes sure you can still get both network stats and tracker stats in the same row for the campaign.

3. Smart, customizable metrics pull the data from the right source in each case.

   In situations where the same stat is offered by both the network and the tracker, e.g., the number of installs per campaign in a given date range, the combined metric gives you a single source of truth, intelligently picking either the tracker stat or the network stat based on standard industry usage.

   For example, the custom_installs metric contains the number of installs from the tracker, unless it is a Self-Attributed Network (SAN) such as Facebook or Twitter, in which case the network stat is more important, and custom_installs contains the network metric.

   If Singular's default choice does not work for your specific case, you can have Singular reconfigure specific metrics for you.

   Note: Custom metrics are unavailable for creative breakdowns. Select either network metrics or tracker metrics.

What if I need to know the source of my metrics?

You may want to know the exact source of each metric for each campaign - for instance, if you are trying to find and troubleshoot significant discrepancies between the network vs. the tracker.

In that case, you can add the network metric (see Available Fields for Network Data) and the tracker metric (see Available Fields for Tracker Data) to the combined report. For example, pull all three install metrics: custom_installs, adn_installs, tracker_installs.

This way, you can use custom_installs as your KPI but still see whether there's a significant difference between adn_installs and tracker_installs.

Available Fields for Combined Data

See the Metrics and Dimensions page for a description of each field.

Summary: What Types of Data are Available for You?

	I use Singular for...
	Analytics + Singular Attribution	Analytics only, but I set up Singular to pull data from my third-party tracker	Pulling data from my ad networks only
Network Data	Available	Available	Available
Tracker Data	Available	Available	-
Combined Fields	Available	Available for Self-Attributing Networks (no creative breakdown)	-

How to Query the Reporting API

After you've decided what type of data you want to query, and made a list of the specific metrics and dimensions you are interested in, here's how to use the reporting API.

Running a Basic Query

1	Query the Create Async Report endpoint (see endpoint reference), specifying the metrics and dimensions you've chosen. This will generate an asynchronous report query and returns a report ID.
2	Using the report ID, query the Get Report Status API endpoint (see endpoint reference) to see when the report has finished running. When the report is done, the Get Report Status endpoint returns a report URL.
3	Download the report from the report URL.

Running Daily Reports

Data in Singular is updated daily. Typically, you would want to pull your data from Singular every day, including:

• Data for yesterday
• Historical data that may have been updated by your networks.

In your regular daily reports, we recommend using the following time windows to pull historical data:

Query Type	Recommended Time Window
Network Data	7 days back.
Tracker Data or Combined Data	A period as long as your longest cohort period. For example, if you have 30-day cohorts, query for 30 days back. If you are not pulling any cohort data such as revenue, pulling 7 days back is usually sufficient.

Checking for Data Availability

You can use the Data Availability Status endpoint to check for each data connector whether Singular has data from that connector for the given date, and when was the last time that data was refreshed.

The most common use for this endpoint is to check if data is already available for yesterday for each of your data connectors. This way, if all data connectors are ready, you can start running reports for all your data. If only some of the data connectors have data while others don't, it's your choice whether to wait for them all to finish or run a report on each data source as its data becomes available. (To run a report on a single data connector in Create Async Report, filter the report by data_connector_id.)

Note that Singular does not recommend running a report on more than one data connector/source in the same query anyway.

Checking for Data Freshness

To see how up-to-date your network data is in Singular, include the dimension data_connector_timestamp_utc in your report query. 

This dimension includes the date and time in which Singular started pulling the data from the data connector (regardless of how long it took to ingest, process, and save the data in the Singular database).

Use case examples for the data timestamp include:

• If you're experiencing discrepancies between Singular reporting and the data in your network dashboard
• If you're using Singular data destinations (ETL) to pull data from Singular into your BI platform and want to see if Singular has newer data