Reporting API FAQ and Troubleshooting

Learn more about the Reporting API and how to solve some common reporting issues.

See also: Using the Singular Reporting API, API Error Codes


How frequently should I run my reports?

For most networks, Singular refreshes the data daily, so running your reports every day is good practice. There is no reason to query the data more frequently. See Running Daily Reports for more information.

What should I do if my report fails?
  1. Check the error code returned by Get Report Status and see if you can find the reason for the failure using the Error Codes index.
  2. If the problem persists, contact Singular's support team. We recommend saving the report ID because the team can use it to find the specific API call that returned the error and check for technical reasons why it couldn't be completed.
I queried the data availability endpoint and data is missing for one or more networks. What should I do?

Generally, your data for yesterday should be ready for you by 8 a.m. in your local timezone. If it isn't ready, check the "status" parameter returned by the Data Availability endpoint. It may include more information about the problem (see the Data Availability Endpoint reference for more information). If there is a login issue (Singular could not log into the source to pull the data), go to the Data Connectors page in the Singular app, and re-enter your credentials.

However, there may not be an immediately identifiable problem such as a login error. Data pulls can be delayed for various reasons. Note that the Singular team is alerted about data delays automatically and immediately begins working on the problem. In the meantime, you can:

  • Query all your other networks and leave the delayed ones for later
  • Wait at least an hour and check again
  • In urgent cases, if you have waited and the source still isn’t populated, you can notify Singular support, but keep in mind that they are probably already working on it.
Why do I get "Missing Creative Data" in the "Creative Name" dimension? Why do the creative metrics contain negative values?

This arises from a workaround to a technical issue with some of the ad networks we pull data from.

Sometimes the ad network’s metrics for the creatives within a campaign don’t add up exactly to the ad network's metric for the campaign.

For example, here is data pulled on the creative level that adds up to 50 clicks, while the data pulled on the campaign level shows 45 clicks for the same campaign:


In such cases, to align the data, Singular adds a dummy creative row to the database, and gives it the value needed so that the metrics for the creatives add up to the metric for the whole campaign. This value is sometimes negative. The Creative Name in this dummy row is given as "Missing Creative Data."


These dummy rows are usually only displayed in API results (not in reports you run in the Singular UI). You can hide them by adding the following to your query: display_alignment=False

Why are metrics for the same campaign broken into separate rows?

Sometimes, instead of getting all the metrics for a campaign in a single row, you will get network metrics (such as cost) in one row, and tracker metrics (such as clicks and installs) in a second row.

When this happens, it’s usually because you requested a dimension that is provided by the ad network and not provided by the attribution tracker, or vice versa. In that case, even if you ran a combined query, the results just couldn't be combined into the same row.

For example, you may get results like the following:


In this example, you can see that the dimension that makes it impossible for Singular to provide a combined row of metrics is Publisher, which the attribution tracker did not provide (at least for this campaign). To get a combined row of data with cost and installs for the campaign, remove the problematic dimension from the query.

Alternatively, you can aggregate the campaign-level results in a separate step afterward in your BI system.

Why am I getting values that don’t make sense in ratio-based calculated metrics (CPE, CPI, etc.)?

Singular offers some metrics that are calculated based on other metrics in the row. For example, CPI (cost per install) is the cost divided by the number of installs. We recommend avoiding using these metrics in API reports because in any aggregated query (where the metrics are added up with a "+" operation), you get meaningless results.

For example:


Why don't my Singular API reports match the values in the Singular user interface?

The Singular API and the Singular user interface (at use the same code to pull the data from the Singular database, so the results should always match. If they don’t, it probably means you haven’t run the exact same query.

Compare your query settings in the Singular user interface to the API query, paying attention to the following differences in particular:

You can also use developer tools to check the get_new_data API call that runs when you use the UI.

Why do I get an "Invalid Filter Value" error?

You get this error when your query included a filter that doesn’t exist. For example, you may have tried to filter by an app that doesn’t exist in your apps page, or an OS that doesn’t exist at all. Examine the returned filter value and fix the query appropriately.

To get a list of all the fields you can filter on and all of the valid values for each field, use the filters endpoint.

Why do I get a 429 error?

You can only run 100 asynchronous reports at the same time. If you've already submitted 100 reports, wait for a report to finish before submitting another one.

Why do I get a 400 error saying "The request contains invalid dimensions"?

If you included custom dimensions in your query, use the Custom Dimensions endpoint to double-check that the dimensions are still available. This error can arise if you or your team have made changes in the Custom Dimensions configuration page since your query was written.

In addition, for custom dimensions, make sure you use the dimension ID (rather than the "display name").

Learn more in the Custom Dimensions FAQ.

Why do I get a 400 error saying "The request contains invalid metrics" or "The request contains invalid cohort periods"?

If you included cohort metrics or events in your query, use the Cohort Metrics endpoint to double-check that the metrics and the periods you used are available. Make sure you used the metric name (rather than the "display name").

What should I do if I get a 500 error ("Internal server error")?

This can occur for various reasons. Wait a few moments and retry the API call. If you are running the same code every day to pull your reports, you should add retries to the code in case of 500 errors.

If the problem persists, contact Singular support.

Was this article helpful?