Guide to the Singular Reporting API

Learn the concepts behind the Singular Reporting API and how to pull the type of data you need.

We recommend reading this guide before you review the Reporting API Reference to build your queries.

 

Welcome to the Reporting API!

The Reporting API offers aggregated stats about your marketing campaigns that you can ingest into your internal BI systems or marketing performance dashboards.

The following guide explains the major concepts underlying the Reporting API and the basics of running a report query. For full reference material on each endpoint and code samples, see Reporting API Reference.

Looking for another feature?

  • Singular also offers Singular Data Destinations (ETL): a premium service that provides an easier way to export data regularly from Singular into your database or BI platform.
  • The Reporting API only offers aggregated data. To export user-level data from Singular's attribution service, see Exporting Attribution Logs.

API Report Types

Singular gathers and standardizes data from different origins, and you will run different kinds of queries depending on the type of data you want to see.

All the queries are run through the same endpoint (Create Async Report) - the difference between them is which fields you include in the query.

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

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.

Screen_Shot_2020-07-01_at_0.14.09.png

Available Fields for Network Data

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

Network Dimensions

Basic dimensions (should be available for all networks):

  • app
  • source
  • adn_campaign_id
  • adn_campaign_name
  • adn_campaign_url

Optional additional dimensions (support varies by network):

  • os
  • platform
  • country_field
  • adn_sub_adnetwork_name
  • adn_account_id
  • adn_account_name
  • adn_sub_campaign_id
  • adn_sub_campaign_name

Keyword and/or publisher breakdown (support varies by network, cannot be pulled in the same query as creative breakdown):

  • keyword_id
  • keyword
  • publisher_id
  • publisher_site_id
  • publisher_site_name

Creative breakdown (support varies by network, usually cannot be pulled in the same query as keyword/publisher):

  • creative_type
  • adn_creative_id
  • adn_creative_name
  • creative_url
  • creative_image
  • creative_text
  • creative_width
  • creative_height
  • creative_is_video
  • asset_id
  • asset_name

Custom Dimensions:

If you have defined custom dimensions based on these default network dimensions, you can pull them using their IDs. Use the Custom Dimensions Endpoint to get all the custom dimensions defined in your account and their IDs.

Network Metrics
  • adn_cost
  • adn_original_cost
  • adn_original_currency
  • adn_impressions
  • adn_clicks
  • adn_installs

Notes:

  • Singular tries to give you the highest level of granularity available, but not all networks provide all dimensions. See Data Connectors in Detail for more information about what data Singular pulls from each source.
  • Stats such as impressions, clicks, and installs reported by an ad network may not match the stats reported by your attribution tracker.

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.

Screen_Shot_2020-07-01_at_0.15.21.png

Having run a query on tracker data, you can join it to your network data in order 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.

Tracker Dimensions

Basic dimensions (should be available for all networks):

  • app
  • source
  • tracker_campaign_id

Optional additional dimensions (support varies by tracker):

  • tracker_campaign_name
  • os
  • platform
  • country_field

Custom dimensions:

If you have defined custom dimensions based on these default tracker dimensions, you can pull them using their IDs. Use the Custom Dimensions Endpoint to get all the custom dimensions defined in your account and their IDs.

Tracker Metrics

Basic metrics:

  • tracker_impressions
  • tracker_clicks
  • tracker_installs
  • tracker_conversions
  • tracker_reengagements
  • daily_active_users

Cohort metrics:

  • revenue
  • original_revenue

For a full list of the cohort metrics you can use, see the Cohort Metrics Endpoint. For more information, see What are cohort metrics?

Note that cohort metrics include ratio-based calculations such as CPE and CPI. We do not recommend using these in API reports (learn more).

Events:

You can pull the stats for any event you have defined. Note that instead of using the event's name as defined in the Singular app, you have to use the event's auto-generated ID, which you can get from the Cohort Metrics Endpoint.

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.

Screen_Shot_2020-07-01_at_0.16.14.png

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 and are processed by Singular in order 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 therefore 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 installs 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.

Dimensions

Basic dimensions (should be available for all networks and trackers):

  • app
  • source
  • unified_campaign_id
  • unified_campaign_name

Optional additional dimensions (support varies by network/tracker):

  • os
  • platform
  • country_field
  • adn_sub_adnetwork_ name
  • adn_account_id
  • adn_account_name
  • sub_campaign_id
  • sub_campaign_name

Keyword and/or publisher breakdown (support varies by network/tracker, cannot be pulled in the same query as creative breakdown):

  • keyword_id
  • keyword
  • publisher_id
  • publisher_site_id
  • publisher_site_name

Creative breakdown (support varies by network, only available for users of Singular's attribution service):

  • creative_type
  • adn_creative_id
  • adn_creative_name
  • creative_url
  • creative_image
  • creative_text
  • creative_width
  • creative_height
  • creative_is_video
  • asset_id
  • asset_name

Custom Dimensions:

If you have defined custom dimensions based on these default dimensions, you can pull them using their IDs. Use the Custom Dimensions Endpoint to get all the custom dimensions defined in your account and their IDs.

Metrics

Basic metrics:

  • adn_cos
  • adn_original_cost
  • adn_original_currency
  • custom_impressions
  • custom_clicks
  • custom_installs
  • tracker_conversions
  • tracker_reengagements
  • daily_active_users

Metrics for video creatives and video-based campaigns:

  • video_views
  • video_views_25pct
  • video_views_50pct
  • video_views_75pct
  • completed_video_views
  • completed_video_view_rate

Cohort metrics:

  • revenue
  • original_revenue

For a full list of the cohort metrics you can use, see the Cohort Metrics Endpoint. For more information, see What are cohort metrics?

Note that cohort metrics include ratio-based calculations such as CPE and CPI. We do not recommend using these in API reports (learn more).

Events:

You can pull the stats for any event you have defined. Note that instead of using the event's name as defined in the Singular app, you have to use the event's auto-generated ID, which you can get from the Cohort Metrics Endpoint.

Notes:

    • Singular tries to give you the highest level of granularity available, but not all networks and trackers support all breakdowns. See Data Connectors in Detail for more information about what data Singular pulls from each source.
  • Creative-level combined reports are only available for users of Singular's attribution service.
  • Custom metrics are unavailable for creative breakdowns. Select either network metrics ("adn_…") or tracker metrics ("tracker_…").

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 3rd-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) -

The Querying Process

For syntax details and sample queries, see the Reporting API Reference.

Running a Report

The main endpoint for getting reporting data from Singular is Create Async Report, which generates an asynchronous report query and returns a report ID.

Once you have the report ID, query the Get Report Status endpoint periodically to see when the report has finished running. When it's done, the Get Report Status endpoint returns a URL from which you can download the report.

Screen_Shot_2020-07-01_at_0.17.35.png

Adding a Data Availability Check

If you want to run a report on dates that include today or yesterday, query the Data Availability endpoint beforehand to see if data for these dates is already available. If the data isn't ready yet, we recommend waiting at least one hour before trying again.

Splitting Your Queries

If you are running a report on all of your Singular data with high granularity, we recommend not putting it all in a single query, as it may be too heavy to be completed. Instead, split your query into a group of queries. We recommend running a separate query for each of your sources (ad networks).

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.

 

Was this article helpful?