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

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

Sample Output

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

Output Details

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. 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

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

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

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

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).

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

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