Getting Started with the Singular Reporting API

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 the Reporting API Reference for the technical details.

Looking for another API?

Or a different 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.

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.

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
  • data_connector_id
  • data_connector_source_name
  • data_connector_username
  • data_connector_timestamp_utc

Optional additional dimensions (support varies by network):

  • os
  • platform
  • country_field
  • region_field
  • city_field
  • dma_id_field
  • dma_name_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

Campaign properties (learn more):

  • bid_type
  • bid_strategy
  • bid_amount
  • campaign_objective
  • standardized_bid_type
  • standardized_bid_strategy
  • original_bid_amount
  • campaign_status
  • min_roas
  • original_metadata_currency

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 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. 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.

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 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.

image1.png

Note: Because of the large amounts of data processed by Singular, we recommend filtering each query to a single source (network) or data connector and to a single day. For example, if you are running a report on your Facebook campaigns for the past 7 days, run 7 separate reports. This ensures your queries will not be too heavy to run.

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.

image2.png

Note on "data connector" vs. "source":

In Singular, a "source" is an ad network partner from which Singular pulls your advertising data. A "data connector" is a tool that connects to an ad network and pulls data from it.

Depending on your setup, you may have multiple data connectors sharing the same source. This means they pull data into Singular from the same platform (but with different account names, settings, etc.).

The Data Availability endpoint returns availability per data connector rather than per source. If you use the new "expanded=true" parameter (recommended), the results include the data_connector_id parameter, which you can use to filter your report.

Tip: data_connector_id is a network field. If you run a report that includes both network and tracker data, including data_connector_id means that network and tracker data will break into separate rows (see Joining Network and Tracker Data). To fix this, when you start to process the results in your BI platform, just group the results by source and don't include the data_connector_id field.

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).

image3.png

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

Tip: data_connector_id is a network field. If you run a report that includes both network and tracker data, including data_connector_id means that network and tracker data will break into separate rows (see Joining Network and Tracker Data).

Was this article helpful?