Reporting API Reference

Learn the syntax for using Singular's Reporting API. Make sure to read Using the Singular Reporting API first for an introduction to the API's concepts and usage.

 

General Information

Authentication

All API requests require an API key. To retrieve the key, log into your account and go to Settings > API. You can insert the key in the api_key parameter in your request, or provide the token under an Authorization HTTP header.

Rate Limits

The default limits for the Singular API are:

  • Async Reports: up to 100 async reports running concurrently.
  • Synchronous Reports: up to 3 synchronous reports running concurrently.
  • Single Report Row Limit: up to 200K rows per query.
  • Daily Global Row Limit: up to 3M rows on a single day (shared among all your queries).

Singular reserves the right to adjust the rate limit for given endpoints in order to continue and provide a high quality of service to all of our customers. Contact us if there's a specific need to exceed the default limitation.

List of Reporting API Endpoints

The following API endpoints are available:

Create Async Report POST https://api.singular.net/api/v2.0/create_async_report Returns aggregated statistics.
Data Availability GET https://api.singular.net/api/v2.0/data_availability_status Before querying Create Async Report, use this endpoint to determine whether for a given day, data is available for each of your sources (data connectors).
Get Report Status GET https://api.singular.net/api/v2.0/get_report_status Returns the status of a given report.
Filters GET https://api.singular.net/api/v2.0/reporting/filters Returns all filtering options available for your reports.
Custom Dimensions GET https://api.singular.net/api/custom_dimensions Returns all the custom dimensions available for your reports.
Cohort Metrics GET https://api.singular.net/api/cohort_metrics Returns all the cohort metrics and cohort periods available for your reports.
Conversion Metrics GET https://api.singular.net/api/conversion_metrics Returns all the conversion metrics available for your reports.

Create Async Report Endpoint

POST https://api.singular.net/api/v2.0/create_async_report

Usage

This is the main endpoint for getting reporting data from Singular. The endpoint generates an asynchronous report query based on the reporting dimensions, metrics, dates, and other details that you specify, and returns the Report ID. The next step is to query the Get Report Status endpoint to see when the report is done and to get a download URL.

Screen_Shot_2020-07-01_at_0.17.35.png

To learn more, see the Querying Process section in the Guide to the Singular Reporting API.

Limitations

  • An API request for a single day does not have a limit on the count of rows returned.
  • A single request can query up to 30 days and has a maximum of 100,000 queried records. Requests querying more than 100,000 records will not succeed and will require additional filtering.
  • When integrating with our API for daily or weekly data pulls we generally recommend splitting multi-day queries to single-day, and iterating over the entire time period.

Sample Query

import requests
url = "https://api.singular.net/api/v2.0/create_async_report"
query_params = {"api_key": "<API KEY>"}
payload = {
  "dimensions":"app,source,os,country_field",
  "metrics": "custom_impressions,custom_clicks,custom_installs",
  "start_date":"2020-01-01",
  "end_date": "2020-01-01",
  "time_breakdown": "all",
  "format": "csv",
  "country_code_format": "iso"
}
response = requests.post(url=url, params=query_params, data=payload)
print(response.text)

Query Parameters

Parameter Format Description Example
Basic Parameters
api_key String API key provided in the Singular console  
start_date Date    
end_date Date    
time_breakdown String Results breakdown by 'day', 'week', 'month' or 'all', which aggregated data over the entire time period  
Field Selection Parameters
dimensions String A comma-separated list of dimensions. See API Report Types for the list of dimensions available based on the type of data you are looking for. See Metrics and Dimensions for more information about each dimension.  
metrics String A comma-separated list of metrics. See API Report Types for the list of metrics available based on the type of data you are looking for. See Metrics and Dimensions for more information about each metric.  
cohort_metrics String A comma-separated list of cohort metrics by name (see What are cohort metrics?). Cohort metrics include any post-conversion events you have defined in the Events page. To retrieve a list of all the available cohort metrics in your account, use the Cohort Metrics endpoint. 'cohort_metrics': '815782610a1ddf,revenue'
cohort_periods String A comma-separated list of cohort periods (see What are cohort metrics?). To retrieve a list of the available cohort periods, use the Cohort Metrics endpoint. 'cohort_periods': '7d,14d,ltv'
Filtering Parameters
app String A comma-separated list of app names to filter the query results by. To retrieve a list of app names, use the Filters endpoint. 'app': 'my_app1,my_app2'
Source String A comma-separated list of ad networks (and other  sources) to filter by. To retrieve a list of ad network names, use the Filters endpoint. 'source': 'facebook,adwords'
filters JSON A JSON list of filter objects where each contains a dimension, operator, and value(s). Use this parameter to apply more advanced filtering. Note that if you specify more than one filter they will be applied with an AND relation. To retrieve a full list of dimensions you can filter by and their potential values, use the Filters endpoint. 'filters': '[{"dimension": "os", "operator": "in","values": [1, 4]}, {"dimension": "source", "operator": "not in", "values": ["adwords"]}]'
Formatting Parameters
format String The format in which the query results will be delivered. Options: "json" (default) or "csv". 'format':'csv'
country_code_format String Either "iso3" (default) or "iso"  
display_alignment Boolean When set to "true", results will include an alignment row to account for any difference between campaign and creative statistics. To learn more, see Why do the creative metrics contain negative values?  

Sample Output

{
    "status": 0,
    "substatus": 0,
    "value": {
        "report_id": "5cfdb747dd464cd09a9c463e5be9691f"
    }
}

Data Availability Endpoint

GET https://api.singular.net/api/v2.0/data_availability_status

Usage

This endpoint returns whether for a given day, data is available for each of your data connectors.

We recommend using this endpoint to check whether data is already available for yesterday before you run your daily report(s).

See also: I queried the data availability endpoint and data is missing for one or more networks. What should I do?

Sample Query

import requests
url = "https://api.singular.net/api/v2.0/data_availability_status"
querystring = {
  "api_key":"<API_KEY>",
  "format": "json",
  "data_date":"2020-01-01",
  "display_non_active_sources":"true"
}
response = requests.get(url=url, params=querystring)
print(response.text)

Query Parameters

Parameter Format Description Example
api_key String API key provided in the Singular console  
format String Output format - "json" or "csv" json
data_date Date The day to check data availability for. 2020-05-01
display_non_active_sources Boolean Whether to include non-active data connectors (data connectors that haven't had data in the last 30 days) in the check. false

Sample Output

{'is_all_data available': false,
'data_sources': [
{'username': u'facebook@singular.net',
 'status': 'data populated',
 'is_empty_data': false,
 'is_active_last_30_days': true,
 'last_updated_utc': '2018-05-03T10:12:18'
 'source': u'Facebook',
 'is_available': true},
 {'username': u'vungle@singular.net',
 'status': 'data populated',
 'is_empty_data': true,
 'is_active_last_30_days': true,
 'last_updated_utc': '2018-05-03T10:12:18'
 'source': u'Vungle',
 'is_available': true},
 {'username': u'applovin@singular.net',
 'status': 'data not populated',
 'is_empty_data': N/A,
 'is_active_last_30_days': true,
 'last_updated_utc': N/A
 'source': u'Applovin',
 'is_available': false}
]}

Output Parameters

Parameter Format Description
is_all_data_available Boolean True if there is data from all data connectors for the given date. Otherwise false.
is_available Boolean True if there is data from the specific data connector for the given date. Otherwise false.
is_empty_data Boolean True if data was pulled successfully from the specific source, but the data is empty (all zeros or "N/A" values).
status String Additional information about the status of the data. The possible values are:
  • "Data Populated"
  • "Data not Populated": No data yet, but no known issues either.
  • "Login Error": Singular couldn’t pull the data because there is a problem with the credentials.
  • "Setup" or "Not configured": The data connector for this source has not been set up, or there is a problem with the configuration.
  • "Disabled": The data connector has been manually disabled.
See I queried the data availability endpoint and data is missing for one or more networks. What should I do?
is_active_last_30_days Boolean True if data was non-zeroes for at least one day in the last 30 days. Otherwise false.
last_updated_utc Timestamp The latest time in which data was saved in the Singular database for this data connector. of the last data update for the queried date. Note: There may be a gap of up to several hours from the moment in which the data is pulled through the data connector to the time it is saved in the database.

Get Report Status Endpoint

GET https://api.singular.net/api/v2.0/get_report_status

Usage

This endpoint returns the status of a given report that was generated using the Create Async Report endpoint. If the report has finished running, the endpoint also returns a download URL.

Screen_Shot_2020-07-01_at_0.17.35.png

If the report has failed, the endpoint returns an error message that you can use to troubleshoot the problem (see the Error Codes table and the API FAQ and Troubleshooting guide).

To learn more, see the Querying Process section in the Guide to the Singular Reporting API.

Important:

  • Reports can sometimes take up to a few minutes to complete.
  • Do not query the report status endpoint more than once every 10 seconds per report.
  • Set a timeout. In some rare cases, a report can get stuck in "Queued" or "Started" status. If the status is not "Done" or "Failed" after 30 minutes, we recommend submitting the report again (which will give you a new report ID to query).

Sample Query

import requests
url = "https://api.singular.net/api/v2.0/get_report_status"
querystring = {
  "report_id":"5cfdb747dd45be9691f",
  "api_key": "<API KEY>"
}
response = requests.get(url=url, params=querystring)
print(response.text)

Query Parameters

Parameter Format Description
api_key String API key provided in the Singular console
report_id String A Report ID returned by the Create Async Report endpoint.

Sample Output

{
  "status": 0,
  "substatus": 0,
  "value": {
      "status": "DONE",
      "url_expires_in": 3600,
      "generated_url_time_in_utc": "2018-05-13T08:26:18.457690+00:00",
      "url_expired_time_in_utc": "2018-05-13T09:26:18.457690+00:00",
      "download_url": "https://singular-reports-results.s3.amazonaws.com/singular/xxxxxxxxx",
      "report_id": "5cfdb747dd45be9691f"
  }
}

Output Parameters

Output Parameter Format Description
status String Possible values:
  • "QUEUED": The report is still waiting in the queue.
  • "STARTED": The report is running.
  • "DONE": The report is ready. See the download_URL parameter for the URL from which you can download the report file.
  • "FAILED": The report failed to complete. Read the attached error message and check the Error Codes table and the API FAQ and Troubleshooting page for assistance.
generated_url_time_in_utc Timestamp  
url_expires_in Integer Seconds until the download URL expires.
url_expired_time_in_utc Timestamp  
download_url URL  
report_id String  

Filters Endpoint

GET https://api.singular.net/api/v2.0/reporting/filters

Usage

Use this helper endpoint to retrieve an up-to-date list of the dimensions you can filter your report by and the possible values for each dimension.

Sample Query

import requests
url = "https://api.singular.net/api/v2.0/reporting/filters"
params = {'api_key': "<API KEY>"}
result = requests.get(url=url, params=params)
print result.json()

Query Parameters

Parameter Format Description
api_key String API key provided in the Singular console

Sample Output

{
  "status": 0,
  "substatus": 0,
  "value": {
    "dimensions": [
      {
        "name": "os",
        "display_name": "OS",
        "values": [
            {"name": 4, "display_name": "Android"},
            {"name": 1, "display_name": "iOS"}
          ],
      },
      {
        "name": "source",
        "display_name": "Source",
        "values": [{"name": "adwords", "display_name": "AdWords"}]
      }
    ]
  }
}

Custom Dimensions Endpoint

GET https://api.singular.net/api/custom_dimensions

Usage

Use this endpoint to retrieve the IDs of any custom dimensions configured for your account. You can then use the custom dimension IDs when querying the Create Async Report endpoint (instead of or in addition to any of the default dimensions).

To learn about custom dimensions and how to create them, see the Custom Dimensions FAQ.

Sample Query

import requests
url = "https://api.singular.net/api/custom_dimensions"
params = {'api_key': "<API KEY>"}
result = requests.get(url=url, params=params)
print result.json()

Query Parameters

Parameter Format Description
api_key String API key provided in the Singular console

Sample Output

{
  "status": 0,
  "substatus": 0,
  "value": {
    "custom_dimensions": [
      {"display_name": "Channel Type", "id": "e471cb6b83684532e5e83cd"},
      {"display_name": "Region", "id": "1dcfdb1ad861fba4b098e2"}
    ]
  }
}

Cohort Metrics Endpoint

GET https://api.singular.net/api/cohort_metrics

Usage

Use this endpoint to retrieve all the cohort metrics and cohort periods available for your account. This includes any in-app events you configured Singular to track (see the Events FAQ). You can then specify these metrics and periods when you run a query in the Create Async Report endpoint.

Note that in the Create Async Report query you need to use the "name" of the metric, not the "display name".

Sample Query

import requests
url = "https://api.singular.net/api/cohort_metrics"
params = {'api_key': "<API KEY>"}
result = requests.get(url=url, params=params)
print result.json()

Query Parameters

Parameter Format Description
api_key String API key provided in the Singular console

Sample Output

{
    "status": 0,
    "substatus": 0,
    "value": {
        "metrics": [
            {"display_name": "ROI","name": "roi"},
            {"display_name": "Revenue","name": "revenue"}
        ],
        "periods": ["1d","3d","5d","7d","14d","30d","actual"]
    }
}

Output Parameters

Output Parameter Format Description
display_name String The name of the metric as it appears in the Singular web app.
name String The identifier of the metric for use in API queries.
periods Array All the cohort periods supported for your account. For more information, see What are cohort metrics and cohort periods?

Conversion Metrics Endpoint

GET https://api.singular.net/api/conversion_metrics

Usage

Use this endpoint to retrieve all the conversion events available for your account. You can then specify these events as metrics when you run a query in the Create Async Report endpoint.

Note that in the Create Async Report query you need to use the "name" of the metric, not the "display name".

Sample Query

import requests
url = "https://api.singular.net/api/conversion_metrics"
params = {'api_key': "<API KEY>"}
result = requests.get(url=url, params=params)
print result.json()

Query Parameters

Parameter Format Description
api_key String API key provided in the Singular console

Sample Output

{
  "status": 0, 
  "substatus": 0, 
  "value": {
    "metrics": [
      {"display_name": "5-second video view", "name": "87dfg34453hsfg6f"}, 
      {"display_name": "5-second video view CPE", "name": "87dfg34453hsfg6fCPE"},   
      {"display_name": "Sign up", "name": "iuq353fidr76w846fha"}, 
      {"display_name": "Sign up CPE", "name": "iuq353fidr76w846fhaCPE"}, 
      {"display_name": "Post engagement", "name": "b59cje9fcgw0th"}, 
      {"display_name": "Post engagement CPE", "name": "b59cje9fcgw0thCPE"},
    ]
  }
}

Output Parameters

Output Parameter Format Description
display_name String The name of the conversion event as configured in the Events page.
name String The auto-generated identifier of the event - use this identifier in your report query.

Error Codes

Singular uses standard HTTP response codes to indicate the success or failure of an API request. In general, 200 codes correspond to success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and 5xx codes are for other issues.

See also: Reporting API FAQ and Troubleshooting

Code Error Text Additional Information
400 An invalid timestamp was given. The timestamp must be of the format: YYYY-MM-DD hh:mm:ss. Specify timestamps as in the following example: 2018-01-01 00:00:01
400 An invalid date was given. The date must be of the format: YYYY-MM-DD. Specify dates as in the following example: 2018-01-20
400 An invalid date range was given. End date must be later than start date.  
400 An invalid time breakdown was given. The time breakdown parameter is either missing in your query or isn't one of the supported options: "day", "week", "month", or "all".
400 An invalid filter was given. Use the Filters endpoint to get the list of filters you can use in your queries.
400 At least one metric must be used. Include at least one metric in your query.
400 The requested data set includes publisher dimensions and extends beyond a single day. Please run single day queries with publisher dimensions. Reports broken down by publisher include large volumes of data. To run these reports, limit them to one day.
400 An invalid result format was given. Please select between JSON and CSV.  
400 An invalid country_code_format was given. Please use "iso3" or "iso".  
400 The request contains invalid dimensions: One or more dimensions you requested in the query are either deprecated or invalid. If you used custom dimensions, double-check that they are available (using the custom dimensions endpoint) and make sure you used the dimension IDs (rather than their display names).
400 The request contains duplicate fields: [list]  
400 The request contains invalid metrics: One or more metrics you requested in the query are either deprecated or invalid. If you used cohort metrics or conversion events, double-check that they are available (using the cohort metrics and conversion events endpoints) and make sure you used the metric names (rather than their display names).
400 The request contains invalid cohort periods: Use the cohort metrics endpoints to check which cohort periods are available for your account.
400 We could not find cohort periods for the following cohort metrics: . Add cohort periods for your cohort metrics.
400 The request contains dimensions from an old API version: . Please use dimensions from the v2 API endpoint only. The request included dimensions from multiple API versions, which is not supported.
400 The request is missing the following parameter: .  
401 An invalid API Key was given. The API key is either missing or invalid. To get your API key, log into your Singular account and go to Settings.
401 The provided API key has been previously deactivated. Please contact your administrator. You are using an API key that belonged to a deactivated user. To get your API key, log into your Singular account and go to Settings.
403 The provided API key does not have permissions to view the field: . The API key provided does not have permissions to view a dimension or metric you requested. Contact your organization's administrator to make sure you have the permissions you need.
403 The request is denied access. Please contact your administrator. The request is denied. Contact your organization's administrator for further information.
404 Report ID is not found. Please correct it or create a new report. Double-check that you used the Report ID returned from the Create Async Report endpoint. If the error persists, create a new report.
404 Report ID was created with a different key. Please use the same key when requesting status. To query for a report status, you must use the same API key you used to generate the report.
405 METHOD NOT ALLOWED You are probably using GET instead of POST or vice versa in your http request.
429 Query quota is exceeded: only <> reports are currently allowed. The following report IDs are active: . You have exceeded the amount of async reports you are permitted to run at the same time. Wait for your previous requests to complete.
429 Too many requests. Only <> requests per second is currently allowed. You have exceeded the rate limit. Wait for your previous requests to complete.
500 The request has failed due to an internal error. Typically, this just means you should retry your API call. See What should I do if I get a 500 error?
Was this article helpful?