General Information

Authentication

All API requests require an API key. To retrieve the key, log into your account and go to Developer Tools > API Keys. 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 Endpoint

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)

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

Available Dimensions and Metrics

See the Metrics and Dimensions Glossary for a description of each field.

Network Data

Tracker Data

Combined Data

Data Availability Endpoint

Usage

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

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

Sample Query (Python)

import requests

  url = "https://api.singular.net/api/v2.0/data_availability_status"
  queryparams = {
    "api_key":"<API_KEY>",
    "expanded":"true",
    "format": "json",
    "data_date":"2021-02-01",
    "display_non_active_sources":"true"
  }
  
  response = requests.get(url=url, params=queryparams)

Query Parameters

Sample Output (when expanded=true)

{
      "status": 0, 
      "substatus": 0, 
      "value": {
          "is_all_data_available": false,
          "data_connectors": [{
              "data_connector_id": "dgd7934875", 
              "data_connector_source_name": "Vungle", 
              "data_connector_username": "ua@mycompany.com", 
              "is_active_last_30_days": true, 
              "is_available": true, 
              "is_empty_data": false, 
              "last_updated_utc": "2021-02-08T10:10:07", 
              "data_connector_timestamp_utc": "2021-02-08T10:10:07", 
              "status": "data populated"
          }, {
              "data_connector_id": "youi293478", 
              "data_connector_source_name": "IronSource", 
              "data_connector_username": "ua@mycompany.com", 
              "is_active_last_30_days": true, 
              "is_available": false, 
              "is_empty_data": "N/A", 
              "last_updated_utc": "N/A", 
              "data_connector_timestamp_utc": "N/A", 
              "status": "data not populated"
          }]
      }
  }

Output Parameters

{'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}
  ]}

Get Report Status Endpoint

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.

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

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

Filters Endpoint

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

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

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

Sample Output

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

Cohort Metrics Endpoint

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

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

Conversion Metrics Endpoint

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

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

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