Migrating to the Singular Async API: FAQ

Starting December 16, 2020, Singular will no longer support synchronous API requests. If you are still using the old endpoints, learn what is being deprecated and how to migrate to the asynchronous API.

 

What endpoints are being deprecated, and why?

Singular is deprecating the following old API endpoints:

The synchronous reporting API endpoint was released back in 2015. Since then, we’ve learned a lot about data management at scale, and even more importantly - about how our customers want to access their data. Synchronous reports require long-lived connections to our servers, and as we’ve substantially increased the granularity we offer (e.g., publisher-level cost), the demand on our systems has grown even further. Switching to asynchronous reports provides a more robust solution to handle intense reporting demands.

Why is the async API better?

The async API offers the following benefits:

  • Improved stability and reliability: By switching to asynchronous requests, we eliminate the need for a long-lived server connection, thus improving reliability and reducing the chance of failed requests.
  • Multiple concurrent reports: The async API allows you to send multiple report requests at the same time. For example, if you're pulling data for 30 days back, you can run 30 report queries (one report per date) concurrently.

What other effects can I expect?

While the change to a managed queue of report requests allows Singular to improve the reliability of the entire platform for all customers, it also means that some of your reports may take a longer time to complete than they did with the sync API.

What API calls do I need to replace?

If you are still using the sync reporting API endpoint (https://api.singular.net/api/v2.0/reporting), you will need to replace your API call with two calls:

  1. A call to the Create Async Report endpoint to generate a report. This is where you specify the dimensions, metrics, filters, etc. This endpoint returns a report ID.

    Learn more in the Create Async Report endpoint reference.

  2. A call to the Get Report Status endpoint with the report ID as a parameter, to find out if the report is done. If the report has finished running successfully, this endpoint returns a link from which you can download the report.

    Learn more in the Get Report Status endpoint reference.

Screen_Shot_2020-07-01_at_0.17.35.png

Are the fields, filters, etc. the same as in the sync reporting endpoint?

Yes, the Create Async Report endpoint uses the same metrics and dimensions, as well as the same logic for filtering. We recommend sticking to the same settings you used in the past as you migrate to the async API.

Read the API Reference for more details and examples. 

For a full list of available fields, see the Metrics and Dimensions guide.

I am using the Last Modified Date endpoint. What calls do I need to replace?

Instead of using Last Modified Date, we recommend pulling data from Singular every day, including data for yesterday and historical data that may have been updated by your sources. 

  • For network data, we recommend pulling 7 days back.
  • For tracker data, we recommend going by your longest cohort. 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.

Is there an alternative to migrating to the async API?

If you're interested in a simpler solution in terms of implementation, consider setting up Singular Data Destinations (ETL). This premium feature will push the Singular data you need regularly into your BI platform or data warehouse. To learn more, see the Data Destinations (ETL) FAQ or contact your Customer Success Manager.

Was this article helpful?