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:
- Query Create Async Report for the data you want from a specific organization.
- 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:
|
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 |