How to Query the Singular Reporting API

Learn how to create an asynchronous report and the best practices for running your daily reports.

Be sure to read  Singular Reporting API: Use Cases and Types of Data first.

For endpoint details, parameters, and code samples, see the API Reference.

 

Running a Basic Query

1

Choose the type of data you want to query: network data, tracker data, or combined data. See Singular Reporting API: Use Cases and Types of Data.

2

Choose the dimensions (breakdowns) and metrics for your report. Each type of query has a different selection of dimensions and metrics available. For a description of each field, see the Singular Metrics and Dimensions Glossary.

3

Query theCreate Async Report API endpoint (see endpoint reference). This will generate an asynchronous report query and returns a report ID.

4

Using the report ID, query the Get Report Status API endpoint (see endpoint reference) 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.

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.

[NEW] 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.

[NEW] 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?