> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.metric.works/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Polaris Reporting API

# 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](#1-filters) 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](#1-group-by). | ```["CHANNEL", "COUNTRY"]``` | Yes |
| metrics | An array that represents the metrics that should be returned. See [Metrics](#1-metrics). | [Example](#2-metrics-example)  | Yes |
| filters | An array that represents the values that results should be filtered on. See [Filters](#1-filters). | [Example](#2-filters-example) | No |
| orderBy | An array that represents the dimensions that the results should be ordered by. See [Order By](#1-order-by). | [Example](#2-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](#1-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](#1-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](#1-limits), 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)
```