Endpoints

The Polaris Reporting API endpoints are:

https://inc-metrics.prod.api.metric.works/token - Obtain security token for authentication
https://inc-metrics.prod.api.metric.works/query - Submit a query to obtain reporting data

Limits

The API has the following limits:

Limit	Value
Request Rate	60 requests per minute per account
Concurrent Requests	1
Date Range	Max 30 days per request
App Filter	1 app per request (use the full App Name in Polaris as the filter value)

Authentication

All requests to the Reporting API's query endpoint must specify a security token obtained from the token endpoint. To obtain a security token, POST a request containing the following JSON body:

{ "username": "my.email@company.com", "password": "mypassword" }

Replace the username and password placeholder values above (my.email@company.com and mypassword) with your actual Polaris username (which is your email address) and password.

If successful, the response will be a text security token that must be specified in your query requests as a Bearer token in the Authorization header like the following:

Authorization: Bearer [security token]

Replace the [security token] placeholder in the header example above with the security token. Security tokens are valid for 1 hour from the time they are obtained from the token endpoint. Specifying an expired security token will result in a 401 Unauthorized response from the query endpoint.

Querying

To query reporting data from the Reporting API, POST a request containing one or more of the following properties:

Property Name	Description	Example	Mandatory
startDate	The desired start date of the results. Format: yyyy-mm-dd.	2021-01-01	Yes
endDate	The desired end date of the results. Format: yyyy-mm-dd.	2021-01-31	Yes
groupBy	An array that represents the dimensions that the results should be grouped by. See Group By.	["CHANNEL", "COUNTRY"]	Yes
metrics	An array that represents the metrics that should be returned. See Metrics.	Example	Yes
filters	An array that represents the values that results should be filtered on. See Filters.	Example	No
orderBy	An array that represents the dimensions that the results should be ordered by. See Order By.	Example	No

Group By

The table below describes the dimensions that can be used as valid values in the groupBy property. The group by can be thought of as the granularity of the returned results.

Value	Description
DATE	Date
PLATFORM	Platform
APP	App
CHANNEL	Channel
CAMPAIGN_GROUP	Campaign
COUNTRY	Country
SITE	Site

Metrics

Each metric object listed in the metrics property must specify the following properties.

Property Name	Description	Example	Mandatory
type	The type of the metric. See the table below for valid values.	COHORT_REVENUE	Yes
day	The cohort day of the metric. Only required when the metric is a cohorted metric.	7	No
interval	Whether or not the 95% confidence interval should also be returned. Only applicable when the metric is an incrementality metric.	true	No

The table below describes the metric types that can be used as valid values in the type property of the each metric object. Metric types prefixed by INC_ are incrementality metrics; others are last touch.

Value	Description	Cohorted
SPEND	Spend	No
NEW_USERS	Installs or registrations	No
INC_NEW_USERS	Incrementality installs or registrations	No
COHORT_SIZE	Cohort size	Yes
INC_COHORT_SIZE	Incrementality cohort size	Yes
RETAINED_USERS	Retained users	Yes
INC_RETAINED_USERS	Incrementality retained users	Yes
COHORT_REVENUE	Cohorted total revenue	Yes
INC_COHORT_REVENUE	Incrementality cohorted total revenue	Yes
COHORT_AD_REVENUE	Cohorted ad revenue	Yes
INC_COHORT_AD_REVENUE	Incrementality cohorted ad revenue	Yes
COHORT_IAP_REVENUE	Cohorted purchase revenue	Yes
INC_COHORT_IAP_REVENUE	Incrementality cohorted purchase revenue	Yes
RETENTION_RATE	Retention rate	Yes
INC_RETENTION_RATE	Incrementality retention rate	Yes
COST_PER_NEW_USER	CPI or cost per acquisition	No
INC_COST_PER_NEW_USER	Incrementality CPI or cost per acquisition	No
ROAS	Return on ad spend	Yes
INC_ROAS	Incrementality return on ad spend	Yes
LTV	Lifetime value or average revenue per user (ARPU)	Yes
INC_LTV	Incrementality lifetime value or average revenue per user (ARPU)	Yes
COHORT_PURCHASES	Cohorted number of purchases or subscriptions	Yes
INC_COHORT_PURCHASES	Incrementality cohorted number of purchases or subscriptions	Yes
COHORT_SESSIONS	Cohorted sessions	Yes
INC_COHORT_SESSIONS	Incrementality cohorted sessions	Yes
COHORT_PAYING_USERS	Cohorted number of unique users with at least one purchase	Yes
INC_COHORT_PAYING_USERS	Incrementality cohorted number of unique users with at least one purchase	Yes
COHORT_PAYING_RATE	Cohorted % of users that made at least 1 purchase	Yes
INC_COHORT_PAYING_RATE	Incrementality cohorted % of users that made at least 1 purchase	Yes

Metrics Example

[
  {
    "type": "INC_NEW_USERS",
    "interval": true
  },
  {
    "type": "NEW_USERS"
  },
  {
    "type": "INC_ROAS",
    "day": 3,
    "interval": false
  },
  {
    "type": "ROAS",
    "day": 3
  }
]

Filters

Each filter object listed in the filters property must specify the following properties.

Property Name	Description	Example	Mandatory
type	The dimension of the filter using any value valid as a group by.	CHANNEL	Yes
values	An array that represents the values that you wish to filter the dimension on.	["Facebook"]	Yes
not	Whether or not the filter should be negated.	false	No

Filters Example

[
  {
    "type": "CHANNEL",
    "values": ["Facebook"],
    "not": false
  }
]

Order By

Each order by object listed in the orderBy property must specify the following properties.

Property Name	Description	Example	Mandatory
type	The dimension of the order by using any value valid as a group by.	CHANNEL	Yes
descending	Whether or not you wish to order descending rather than the default ascending.	false	No

Order By Example

[
  {
    "type": "CHANNEL",
    "descending": false
  }
]

Code Sample

The following is a code sample written in Python. It implements no fault tolerance, error handling, or throttling, but should provide an idea of the basics.

import requests

token_endpoint = "https://inc-metrics.prod.api.metric.works/token"
query_endpoint = "https://inc-metrics.prod.api.metric.works/query"

username = "username"
password = "password"

credentials = {
    "username": username,
    "password": password
}

query = {
    "groupBy": [
        "CHANNEL"
    ],
    "metrics": [
        {
            "type": "INC_NEW_USERS",
            "interval": True
        }
    ],
    "filters": [
        {
            "type": "APP",
            "values": ["App Name (iOS)"]
        }
    ],
    "order": [],
    "startDate": "2022-06-01",
    "endDate": "2022-06-01"
}

token_response = requests.request("POST", token_endpoint, json=credentials)

headers = {'Authorization': 'Bearer ' + token_response.text}

query_response = requests.request("POST", query_endpoint, headers=headers, json=query)

print(query_response.text)

Updated on: 31/10/2024