Reporting API for Singular Partners

This guide is aimed at Singular partners. Partners can access some of their advertisers' data, either through the Partner Portal or via API.

If you are a Singular customer, see the Reporting API Reference and Getting Started with the Singular Reporting API instead.

As a Singular partner, you can use the Singular Reporting API to access data for your Singular-enabled advertisers.

The data you can access through the API for each organization is the same as the data available in the Partner Portal.

Basics of the Reporting API

Before you run a report, you will need the following information:

  • Your Singular API key. You can find it in the Partner Portal (see the Using the Partner Portal).
  • The organization key for the advertiser you want to access. Query the Get Customer Accounts API endpoint to get the list of advertiser names and the unique organization key for each one.
  • Report filtering options. Query the Filters endpoint using your API key and the advertiser's organization key. The options are different for each organization.
  • Events and cohort periods. Check the Partner Portal. Any events that are available in the portal for the specific advertiser will also be available to you through the API.

To run reports, use the two main endpoints:

  1. Query Create Async Report for the data you want from a specific organization.
  2. Query Get Report Status to see the status of a given report and access the report once it's done running.

Get Customer Accounts Endpoint

Get https://api.singular.net/api/v2.0/get_customer_accounts

Usage

Use this endpoint to retrieve your list of advertisers. The list of advertisers includes all the Singular customers running campaigns in your network, minus any customers who have opted out of sharing the data with you.

You can then use the organization key to query the Create Async Report endpoint.

Query Parameters

Parameter Format Description
api_key String Your Singular API Key

Sample Output

"organizations": [
    {
        "display_name": "Awesome Games",
        "organization_key": "aw_games"
    },   
    ...
]

Output Details

Parameter Description
display_name The advertiser's full name
organization_key The advertiser's unique key in Singular (use for querying the Create Async Report endpoint).

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. You have to specify the specific advertiser organization you are interested in.

Sample Query (Python)


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

Query Parameters

Parameter Format Description
api_key String Your API key as provided in the Partner Portal
organization_key String The organization key as returned by the Get Customer Accounts endpoint

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"}
        ]
      }
    ]
  }
}

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 organization key, reporting dimensions, metrics, dates, and other details 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.

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 into a single day, and iterating over the entire time period.

Sample Query (Python)


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

Query Parameters

Parameter Format Description Example
Basic Parameters
api_key String Your API key provided in the Partner Portal.  
organization_key String The organization key for the advertiser you want to run a report on.  
start_date Date    
end_date Date    
time_breakdown String Results breakdown by 'day', 'week', 'month', or 'all'. 'all' shows aggregated data over the entire time period.  
Field Selection Parameters
dimensions String A comma-separated list of dimensions. See Supported Dimensions below for the available dimensions you can choose from. See Metrics and Dimensions for more information about each dimension.  
metrics String A comma-separated list of metrics you want in your report. See Supported Metrics below for the available metrics you can choose from. 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 of the advertiser's custom events. The cohort metrics and custom events available for each advertiser can be seen in the Partner Portal. 'cohort_metrics': '815782610a1ddf,revenue'
cohort_periods String A comma-separated list of cohort periods (see What are cohort metrics?). The cohort periods available for each advertiser can be seen in the Partner Portal. '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 object 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"
  }
}

Available Dimensions and Metrics

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

Supported Dimensions:

adn_account_id 
adn_account_name 
adn_campaign_id 
adn_campaign_name
adn_campaign_url 
adn_original_currency 
adn_sub_adnetwork_name 
app
app_id 
country_field 
keyword 
os 
platform 
publisher_id 
publisher_site_name
source 
tracker_campaign_name 
unified_campaign_id 
unified_campaign_name

Supported Metrics:

adn_clicks 
adn_installs 
custom_impressions 
custom_clicks 
custom_installs
tracker_clicks 
tracker_impressions 
tracker_installs 
tracker_reengagements

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 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 you can use to troubleshoot the problem (see the Error Codes table and the API FAQ and Troubleshooting guide).

Notes:

  • 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 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 (Python)

import requests
url = "https://api.singular.net/api/v2.0/get_report_status"
querystring = {
  "report_id":"<REPORT ID FROM CREATE_ASYNC_REPORT>",
  "api_key": "<API KEY>"
} 
response = requests.get(url=url, params=querystring)

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 Details

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