Adjust Help Center

Resources • KPI Service

Adjust KPI Service

The Adjust KPI Service is a pull API to Adjust, with which you can programmatically request statistics for the mobile apps you track with us. The following is a documentation of the RESTful JSON API making this possible.

Before you begin

Here’s what you need to know before getting started.

Availability

The KPI Service is only available for clients on a Business Pro package or above

Helpful information

The following page contains examples using a minimum-length tracker token. Always use the entire tracker token as displayed in your Adjust Campaign Wizard.

There are three types of queries that you can issue to the API: Overview, Events and Cohorts. These largely mirror different sections in the Adjust dashboard, and allow you to pull the relevant KPIs directly.

Each of these queries can be made for either all of an app's Network trackers or for a given parent tracker. Thus each resource has two endpoints: one without a tracker token, by default grouping data for all Network trackers, and another one allowing you to specify a tracker token and drill down into specific sub-tracker groups.

Before getting started with the KPI API specs, you can also look at the R client that we developed to complement it. This client makes it easy and straightforward to bring your Adjust data into your R sessions.

Since the concept of trackers is essential to making sense of the API data, make sure you are familiar with tracker terminology and the hierarchical composition of Network, Campaign, Adgroup and Creative sublevels.

Versioning

The API versions major releases. To avoid confusion, the API version is explicitly written in the URL paths for all endpoints. For example, you’ll be accessing http://api.adjust.com/kpis/v1/.. for version 1.

Response Formats

The API supports two response formats - CSV and JSON, with JSON as default. To specify a different format you can either suffix the endpoints accordingly (e.g. add .csv at the end of endpoint path) or send an Accept: text/csv HTTP header with your request. Throughout this document we mainly use JSON for exemplifying requests and responses.

Authentication

Your access to the KPI Service is tied to your Adjust user account. Each user account has an associated user token, to allow you to individually control access to your KPIs.

You can find your own user token in the dashboard, under Account Settings > Your Data > User Details. This is the user token we’ll be referring to for your authentication below.

Each user token has the same limitations as the dashboard user. That is, if you set custom user permissions, their access via the KPI Service will follow the same rules as their dashboard access.

You can at any time renew your user token.

To authenticate against the API using your user token you have two options and you can pick whichever one you prefer for a given use case:

As an HTTP GET parameter - append user_token=your_user_token to any API query.
As an HTTP Authentication header - add the following HTTP header: `Authorization: Token token=your_user_token`

All examples in this document assume an HTTP Header authentication, but you can easily append a GET parameter with the correct token to the examples and they would still be valid.

App Token and Tracker Token

Let’s try to avoid any confusion and mention that in all Endpoints documented here, the :app_token and :tracker_token parts will have to be replaced by actual token values to get a valid request URL. For example:

https://api.adjust.com/kpis/v1/2eb2na2w54c3/trackers/15jvui

would be the valid URL for app token 2eb2na2w54c3 and tracker token 15jvui. All examples in this document use the app token 2eb2na2w54c3 and you can simply replace that with your own app tokens.

Overview Queries

Overview queries provide data for App KPIs as well as Event KPIs. You will typically be interested in metrics such as clicks, sessions, installs, etc. over a given period for either all networks your app runs on, or for a given parent tracker. You can also request KPIs for your custom Adjust events, such as revenue, first_events, etc. Furthermore, optional country, platform and device scoping could be applied as well.

Endpoints

GET https://api.adjust.com/kpis/v1/:app_token{.csv|.json} 
GET https://api.adjust.com/kpis/v1/:app_token/trackers/:tracker_token{.csv|.json}

Query Parameters

A list of supported query parameters is given here; see also the details on expected parameter values.

Param Name	Format	Description
`start_date`	YYYY-MM-DD	The start date of the selected period.
`end_date`	YYYY-MM-DD	The end date of the selected period.
`utc_offset`	[+-]HH:MM, e.g. `utc_offset=-05:00` or `utc_offset=10:00`	UTC offset for timezones
`kpis`	string, e.g. `clicks,installs,maus`	Comma-separated list of App KPIs. Any combination of App KPIs is accepted.
`event_kpis`	string, e.g. `token1_events,token1_revenue_per_user`	Comma-separated list of Event KPIs. Each KPI should be prefixed with either an event token or `all`. See below for examples.
`reattributed`	string `true`, `false`, or `all`	Filter KPIs by installed or reattributed users only or by all users (default)
`sandbox`	string `true` or `false`	Requests could be issued for Sandbox or Production data. By default, Production is assumed.
`impression_based`	string `true` or `false`	Requests could be issued as click or impression based view. By default, click based is assumed.
`attribution_type`	string `click`, `impression`, or `all`	Click, impression, or click and impression combined (this overrides the `impression_based` parameter)
`attribution_source`	string, `first` or `dynamic`	Determines whether in-app activity is assigned to the user’s install source (`first`) or divided among the install source and subsequent sources of reattribution (`dynamic`). The default setting is `dynamic`.
`countries`	string, e.g. `de,us`	Comma-separated list of `ISO 3166 alpha-2` country names.
`os_names`	string, e.g. `ios,android`	Comma-separated list of OS names. Find the valid OS names below.
`device_types`	string, e.g. `phone,tablet`	Comma-separated list of device types. Find the valid device types below.
regions	string, e.g., `APAC, EMEA`	Comma-separated list of standard or account-specific business regions. Add `+` or `-` before the region name to include (default) or exclude it.
`grouping`	string, e.g. `trackers,countries`	Grouping parameters. See below for more details on grouping.
`cohort_revenue_period`	string, e.g `15d`, [`1d-30d`, `60d`, `90d`, `120d`]	Result should only sum up revenue of the first n days after attribution.

App KPIs

The list of supported App KPIs - that you may pass as values to the kpis parameter - is given below.

App KPI	Description
`clicks`	Number of clicks
`impressions`	Number of impressions
`installs`	Number of installs
`uninstalls`	Number of uninstalls
`uninstall_cohort`	Number of uninstalls from users who installed within your selected timeframe
`reinstalls`	Number of reinstalls
`click_conversion_rate`	Click conversion rate (an average of `installs`/`clicks` weighted by `clicks`).
`ctr`	Click through rate (`clicks`/`impressions` weighted by `impressions`).
`impression_conversion_rate`	Impression conversion rate (an average of `installs`/`impressions` weighted by `impressions`).
`reattributions`	Number of reattributions
`reattribution_reinstalls`	Number of reinstalls that also led to a reattribution
`deattributions`	Number of deattributions
`sessions`	Number of sessions
`revenue_events`	Number of revenue events
`revenue`	Total revenue (in the app's reporting currency)
`all_revenue`	`revenue` + `ad_revenue`
`cohort_revenue`	Total revenue from users who were (re)attributed within your selected timeframe
`daus`	Average daily active users
`waus`	Average weekly active users
`maus`	Average monthly active users
`limit_ad_tracking_installs`	Number of installs from devices with Limit Ad Tracking enabled
`limit_ad_tracking_install_rate`	Proportion of installs from devices with Limit Ad Tracking enabled: `limit_ad_tracking_installs`/`installs`
`limit_ad_tracking_reattributions`	Number of reattributions from devices with Limit Ad Tracking enabled
`limit_ad_tracking_reattribution_rate`	Proportion of installs from devices with Limit Ad Tracking enabled: `limit_ad_tracking_reattributions`/`reattributions`
`gdpr_forgets`	The total number of users who have exercised their right to be forgotten. Adjust permanently deletes the historical personal data for all of these users but retains their aggregated data for dashboard reporting. Their device data will no longer be received by Adjust or appear anywhere in the Adjust dashboard in the future.
`cohort_ad_revenue`	Total ad revenue from users who installed in your selected timeframe
`cohort_all_revenue`	`cohort_revenue` + `cohort_ad_revenue`

Fraud KPIs

Fraud KPIs are only available for accounts with the Adjust Fraud Prevention Suite enabled.

Fraud KPI	Description
`rejected_installs`	Number of rejected installs. This is the sum of `rejected_installs_anon_ip` + `rejected_installs_too_many_engagements` + `rejected_installs_distribution_outlier` + `rejected_installs_click_injection`
`rejected_installs_anon_ip`	Number of rejected installs due to anonymous IP
`rejected_installs_too_many_engagements`	Number of rejected installs due to too many engagements
`rejected_installs_distribution_outlier`	Number of rejected installs due to distribution outliers
`rejected_installs_click_injection`	Number of rejected installs due to engagement injection
`rejected_installs_invalid_signature`	Number of rejected installs due to a missing or invalid SDK Signature
`rejected_reattributions`	Number of rejected reattributions. This is the sum of `rejected_reattributions_anon_ip` + `rejected_reattributions_too_many_engagements` + `rejected_reattributions_distribution_outlier` + `rejected_reattributions_click_injection`
`rejected_reattributions_anon_ip`	Number of rejected reattributions due to anonymous IP
`rejected_reattributions_too_many_engagements`	Number of rejected reattributions due to too many engagements
`rejected_reattributions_distribution_outlier`	Number of rejected reattributions due to distribution outliers
`rejected_reattributions_click_injection`	Number rejected reattributions due to engagement injection
`rejected_install_rate`	Rejected install rate: `rejected_installs`/`(installs + rejected_installs).`
`rejected_install_anon_ip_rate`	Rate of rejected installs due to anonymous IP: `rejected_installs_anon_ip`/(`installs` + `rejected_installs`).
`rejected_install_too_many_engagements_rate`	Rate of rejected installs due to too many engagements: `rejected_installs_too_many_engagements`/(`installs` + `rejected_installs`).
`rejected_install_distribution_outlier_rate`	Rate of rejected installs due to distribution outliers: `rejected_installs_distribution_outlier`/(`installs` + `rejected_installs`).
`rejected_install_click_injection_rate`	Rate of rejected installs due to engagement injection: `rejected_installs_click_injection`/(`installs` + `rejected_installs`)
`rejected_reattribution_rate`	Rejected reattributions rate: `rejected_reattributions`/(`reattributions` + `rejected_reattributions`).
`rejected_reattribution_anon_ip_rate`	Rate of rejected reattributions due to anonymous IP: `rejected_reattributions_anon_ip`/(`reattributions` + `rejected_reattributions`).
`rejected_reattribution_too_many_engagements_rate`	Rate of rejected reattributions due to too many engagements: `rejected_reattributions_too_many_engagements`/(`reattributions` + `rejected_reattributions`).
`rejected_reattribution_distribution_outlier_rate`	Rate of rejected reattributions due to distribution outliers: `rejected_reattributions_distribution_outlier`/(`reattributions` + `rejected_reattributions`).
`rejected_reattribution_click_injection_rate`	Rate of rejected reattributions due to engagement injection: `rejected_reattributions_click_injection`/(`reattributions` + `rejected_reattributions`)

Cost KPIs

Cost KPIs are only available for accounts with cost data enabled.

Cost KPI	Description
`install_cost`	Install cost
`click_cost`	Click cost
`impression_cost`	Impression cost
`cost`	The sum of `click_cost` + `impression_cost` + `install_cost`
`paid_installs`	The number of installs, for which there is cost data
`paid_clicks`	The number of clicks, for which there is cost data
`paid_impressions`	The number of impressions, for which there is cost data
`ecpc`	Effective cost per click, i.e. `cost` / `paid_clicks`
`ecpm`	Effective cost per mille (thousand impressions), i.e. `cost` / `paid_impressions` * 1000
`ecpi`	Effective cost per install, i.e. `cost` / `paid_installs`
`cohort_gross_profit`	The gross profit, i.e. `cohort_revenue` - `cost`
`return_on_investment`	The ROI metric derived by `cohort_gross_profit` / `cost`
`rcr`	The revenue-to-cost ratio derived by `cohort_revenue` / `cost`
`roas`	Return on ad spend, the ROA metric derived by `cohort_ad_revenue/cost *100`

Note: costs are returned in their full reporting currency. I.e., 5.45661 Euros would return cost=5.45661

Ad Revenue KPIs

Ad Revenue KPI	Description
`ad_revenue`	Total revenue (in the app's reporting currency) from ad_impressions
`ad_impressions`	Number of ad_impressions
`ad_rpm`	ad_revenue per mille (thousand impressions), i.e. `ad_revenue / ad_impressions * 1000`

Event KPIs

See the list of supported Event KPIs that you can pass, prepended with an event_token, to the event_kpis parameter on an Overview request. These Event KPIs are also used on Events requests as discussed in the Events section.

Event KPI	Description
`revenue_events`	Number of revenue events
`revenue`	Total revenue in the app's reporting currency
`events`	Number of events
`first_events`	Number of events triggered for the first time by a user. Think about `first_events` to `events` the way you would think about `installs` to `sessions`!
`revenue_per_event`	Total revenue divided by number of events
`revenue_per_revenue_event`	Total revenue divided by number of revenue events

Facilitation for Event KPI requests

This section is only relevant if you plan to request event_kpis with your Overview requests. In the other case, you may skip reading this.

Specifying the event_kpis individually may rapidly result in very long parameters. For example, the below is a valid value for event_kpis:

event_kpis=token1_events,token2_events,token1_revenue,token2_revenue

For this reason, some shortcuts are supported. This string:

event_kpis=token1_revenue|events|revenue_per_event

is equivalent to

event_kpis=token1_revenue,token1_events,token1_revenue_per_event

Furthermore, the special keyword all can be used to expand to all defined events. For example, if you have two events with tokens token1 and token2, the value:

event_kpis=all_revenue|events|revenue_per_event

would be equivalent to

event_kpis=token1_revenue,token1_events,token1_revenue_per_event,token2_revenue,token2_events,token2_revenue_per_event

Finally, this string:

event_kpis=all_revenue,all_events,all_revenue_per_event

would be equivalent to

event_kpis=token1_revenue,token2_revenue,token1_events,token2_events,token1_revenue_per_event,token2_revenue_per_event

Note that the difference between the last two formats is how the order of the metrics is determined. More on that below.

Examples

Requesting only App KPIs

Request:

GET http://api.adjust.com/kpis/v1/2eb2na2w54c3?start_date=2015-05-01&end_date=2015-05-31&kpis=sessions,installs&countries=de,gb

Response:

{
  "result_parameters": {
    "kpis": ["sessions", "installs"],
    "start_date": "2015-05-01",
    "end_date": "2015-05-31",
    "sandbox": false,
    "countries": ["de", "gb"],
    "trackers": [
      {
        "token": "foobar",
        "name": "Network 1",
        "has_subtrackers": true
      },
      {
        "token": "15jvui",
        "name": "Network 2",
        "has_subtrackers": true
      }
    ],
    "grouping": ["trackers"]
  },
  "result_set": {
    "token": "2eb2na2w54c3",
    "name": "app name",
    "currency": "USD",
    "trackers": [
      {
        "token": "foobar",
        "kpi_values": [100, 299]
      },
      {
        "token": "15jvui",
        "kpi_values": [557, 880]
      }
    ]
  }
}

Notice the one-to-one correspondence between the kpis array in the result_parameters and the kpi_values arrays in result_set. The tracker Network 1 in this response has for example 100 sessions and 299 installs.

Requesting App and Event KPIs

In addition to the kpis parameter, you can also request Event KPIs using the event_kpis parameter.

Request:

GET http://api.adjust.com/kpis/v1/2eb2na2w54c3?start_date=2015-05-01&end_date=2015-05-31&kpis=clicks&event_kpis=token1_events,token1_revenue&countries=de,gb

Response:

{
  "result_parameters": {
    "kpis": ["clicks", "token1_events", "token1_revenue"],
    "start_date": "2015-05-01",
    "end_date": "2015-05-31",
    "sandbox": false,
    "countries": ["de", "gb"],
    "trackers": [
      {
        "token": "foobar",
        "name": "Network 1",
        "has_subtrackers": true
      },
      {
        "token": "15jvui",
        "name": "Network 2",
        "has_subtrackers": true
      }
    ],
    "events":[
      {
        "name": "YourEventName",
        "token": "token1"
      }
    ],
    "grouping": ["trackers"]
  },
  "result_set": {
    "token": "2eb2na2w54c3",
    "name": "app name",
    "currency": "USD",
    "trackers": [
      {
        "token": "foobar",
        "kpi_values": [221, 100, 299.30]
      },
      {
        "token": "15jvui",
        "kpi_values": [1005, 557, 880.75]
      }
    ]
  }
}

Notice the one-to-one correspondence between the kpis array in the result_parameters and the kpi_values arrays in result_set. Thus the tracker Network 1 in this response has 221 clicks, 100 occurrences of events with token token1 and 299.30 revenue from those events.

KPI Ordering

Note that the order in which you request kpis and/or event_kpis determines the order of the response you’ll receive. The latter example above illustrates this.

This KPI ordering might be especially useful when you request csv data from the API. In this case, the columns of the response would exactly match the way you request the KPIs.

Event Queries

This section deals with Event KPI queries. These endpoints are useful if you want data grouped by events.

Endpoints

GET https://api.adjust.com/kpis/v1/:app_token/events{.csv|.json} 
GET https://api.adjust.com/kpis/v1/:app_token/trackers/:tracker_token/events{.csv|.json}

Query Parameters

A list of supported query parameters is given here; see also the details on expected parameter values.

Param Name	Format	Description
`start_date`	YYYY-MM-DD	The start date of the selected period
`end_date`	YYYY-MM-DD	The end date of the selected period
`utc_offset`	&[+-]HH:MM, e.g. `utc_offset=-05:00` or `utc_offset=10:00`	UTC offset for timezones
`kpis`	string, e.g. `revenue_events,revenue`	Comma-separated list of Event KPIs. Any combination of Event KPIs is accepted.
`sandbox`	string `true` or `false`	Requests could be issued for Sandbox or Production data. By default, Production is assumed.
`events`	string, e.g. `event_token1,event_token2`	Comma-separated list of Event Tokens. You’ll find the Event Tokens for your events in the Adjust dashboard.
`attribution_type`	string `click`, `impression`, or `all`	Click, impression, or click and impression combined (this overrides the `impression_based` parameter)
`attribution_source`	string, `first` or `dynamic`	Determines whether in-app activity is assigned to the user’s install source (`first`) or divided among the install source and subsequent sources of reattribution (`dynamic`). The default setting is `dynamic`.
`countries`	string, e.g. `de,us`	Comma-separated list of `ISO 3166 alpha-2` country names
`os_names`	string, e.g. `ios,android`	Comma-separated list of OS names. Find the valid OS names below.
`device_types`	string, e.g. `phone,tablet`	Comma-separated list of device types. Find the valid device types below.
`partner_ids`	integer, e.g., `1234,789`	Comma-separated list of partner IDs. Only data from trackers belonging to these partners will be shown.
`grouping`	string, e.g. `trackers,countries`	Grouping parameters. See below for more details on grouping.

Event KPIs

The list of Event KPIs remains the same as above. However, note that unlike Overview queries, in the Events requests you don’t prefix the Event KPIs with an event token. If you want data for specific events, use the events parameter to supply their event tokens.

Example

Request:

GET http://api.adjust.com/kpis/v1/2eb2na2w54c3/events?start_date=2015-05-01&end_date=2015-05-31&kpis=revenue,events,revenue_per_event&grouping=trackers,weeks,events&countries=de,gb

Response:

{
  "result_parameters": {
    "kpis": ["revenue", "events", "revenue_per_event"],
    "start_date": "2015-05-01",
    "end_date": "2015-05-31",
    "sandbox": false,
    "countries": ["de", "gb"],
    "events": [{"token": "abcdef","name": "Login"}, {"token": "badcfe","name": "Level Up"}],
    "grouping": ["trackers", "weeks", "events"],
    "trackers": [
      {
        "token": "foobar",
        "name": "Network 1",
        "has_subtrackers": true
      }
    ]
  },
  "result_set": {
    "token": "2eb2na2w54c3",
    "name": "app name",
    "currency": "USD",
    "trackers": [
      {
        "token": "foobar",
        "dates": [
          {
            "date": "2015-05-02",
            "events": [
              {
                "token": "abcdef",
                "kpi_values": [4, 5, 0.8]
              },
              {
                "token": "badcfe",
                "kpi_values": [3, 5, 7.2]
              }
            ]
          },
          {
            "date": "2015-05-09",
            "events": [
              {
                "token": "badcfe",
                "kpi_values": [4, 5, 0.8]
              }
            ]
          }
        ]
      }
    ]
  }
}

Note the one-to-one correspondence between the kpis array in the result_parameters and the kpi_values in the result_set. In this response, the event “Login” has been recorded 5 times with a revenue_per_event of 0.8.

Cohort Queries

Cohort queries allow you to query data that has been aggregated by user cohort, e.g. a date on which the user has installed/made a purchase/registered etc. This allows you to retrieve cohort-based KPIs such as retention by day after install.

Cohorts should be denominated by cohort period and KPI base. The period describes the segmentation depth of the data, either showing weekly cohorts (e.g. users who installed in a given day, week or month) and KPIs based on this period (e.g. retention by day, week, or month after install). The KPI base defines the user subset between all users, paying users (who have triggered at least one revenue event), and users who have triggered an arbitrary event.

As of May 1st, 2019, we offer support for cohort queries up to 120 days and 52 weeks. You can run a cohort query for a specific day, for a range of days (or both), or a specific week or range of weeks using the cohort_period_filter placeholder.

To query a specific day (for example, the 30th day after install), use the format cohort_period_filter=30

To query a range of days (for example, the first 30 days after install), use the format cohort_period_filter=0-30

To query both a specific day and a range of days simultaneously (for example, the first 30 days after install and day 120), use the format cohort_period_filter=0-30,120

To query a specific week (for example, the 10th week after install), use the format cohort_period_filter=10&period=week

To query a range of weeks (for example, the first ten weeks after install), use the format cohort_period_filter=0-10&period=week

Endpoints

GET /kpis/v1/:app_token/cohorts{.csv|.json} 
GET /kpis/v1/:app_token/trackers/:tracker_token/cohorts{.csv|.json}

Query Parameters

A list of supported query parameters is given here; see also the details on expected parameter values.

Param Name	Format	Description
`start_date`	YYYY-MM-DD	The start date of the selected period
`end_date`	YYYY-MM-DD	The end date of the selected period
`utc_offset`	[+-]HH:MM, e.g. `utc_offset=-05:00` or `utc_offset=10:00`	UTC offset for timezones
`kpis`	string, e.g. `revenue_events,revenue`	Comma-separated list of App KPIs. Any combination of App KPIs is accepted.
`sandbox`	string `true` or `false`	Requests could be issued for Sandbox or Production data. By default, Production is assumed.
`attribution_type`	string `click`, `impression`, or `all`	Click, impression, or click and impression combined (this overrides the `impression_based` parameter)
`attribution_source`	string, `first` or `dynamic`	Determines whether in-app activity is assigned to the user’s install source (`first`) or divided among the install source and subsequent sources of reattribution (`dynamic`). The default setting is `dynamic`.
`period`	one of `day`/`week`/`month`	The cohort period
`reattributed`	one of `true`/`false`/`all`	Control whether cohort is based on reattributions (`true` or `false`). Default value, `all`, includes both reattributions and installs. Data available from October 1 2016
`events`	string, e.g. `abcdef,12345`	Comma-separated list of event tokens
`countries`	string, e.g. `de,us`	Comma-separated list of `ISO 3166 alpha-2` country names
`os_names`	string, e.g. `ios,android`	Comma-separated list of OS names. Find the valid OS names below.
`device_types`	string, e.g. `phone,tablet`	Comma-separated list of device types. Find the valid device types below.
`grouping`	string, e.g. `trackers,install_date`	Grouping parameters. See below for more details on grouping.

Note: The time periods used for the period query parameter are measured by hours after install, not calendar days. This means if a user installs at 12:47 on a Wednesday, week 0 for that user will conclude at 12:47 the following Wednesday (168 hours later), and month 0 will conclude at 12:47 30 days (720 hours) later.

Cohort KPIs

Cohort KPI	Description
`retained_users`	number of users that came back in period
`cohort_size`	for the N-th period-after-install, the number of users who installed at least N periods ago
`retention_rate`	`retained_users` divided by `cohort_size`
`sessions`	number of sessions generated per period
`sessions_per_user`	number of sessions divided by `retained_users`
revenue	amount of revenue per period
`revenue_total`	accumulated revenue for this and all previous periods
`revenue_events_total`	accumulated number of `revenue_events` for this and all previous periods
`revenue_per_user`	`revenue` divided by `cohort_size`
`revenue_per_paying_user`	`revenue` divided by `paying_user_size`
`revenue_total_in_cohort`	for the N-th period-after-install, the revenue accumulated over all periods from 0 to N, from users who installed at least N periods ago
`revenue_events_total_in_cohort`	for the N-th period-after-install, the number of revenue_events accumulated over all periods from 0 to N, from users who installed at least N periods ago
`lifetime_value`	`revenue_total_in_cohort`divided by `cohort_size`
`paying_user_lifetime_value`	`revenue_total_in_cohort`divided by `paying_user_size`
`time_spent`	the sum of time (in seconds) users spent in period,
`time_spent_per_user`	`time_spent` divided by `cohort_size`
`time_spent_per_session`	`time_spent` divided by `sessions` *
`paying_users`	the number of paying users in period
`paying_user_size`	for the N-th period-after-install, the number of paying users who installed at least N periods ago
`paying_users_retention_rate`	`paying_users` divided by `retained_users`
`paying_user_rate`	`paying_users` divided by `cohort_size`
`revenue_events`	the number of revenue events per period
`revenue_events_per_user`	`revenue_events` divided by `cohort_size`
`revenue_events_per_active_user`	`revenue_events` divided by `retained_users`
`revenue_events_per_paying_user`	`revenue_events` divided by `paying_users`
`converted_users`	for the N-th period-after-install, the number of unique users who triggered the given event/events. One user might contribute to multiple days-after-install.
`converted_user_size`	for the N-th period-after-install, the number of converted users who installed at least N periods ago
`conversion_distribution`	`converted_users` divided by `converted_user_size`
`conversion_per_user`	`converted_users` divided by `cohort_size`
`conversion_per_active_user`	`converted_users` divided by `retained_users`
`events`	number of events triggered in period
`events_per_converted_user`	`events` divided by `converted_users`
`events_per_user`	`events` divided by `cohort_size`
`events_per_active_user`	`events` divided by `retained_users`
`reattributions`	number of reattributions generated per period
`deattributions`	number of deattributions (first time reattribution) generated per period
`reattributions_per_user`	`reattributions` divided by `cohort_size`
`deattributions_per_user`	`deattributions` divided by `cohort_size`
`reattributions_per_deattribution`	`reattributions` divided by `deattributions`
`uninstalls`	number of uninstalls per period
`uninstalls_total`	number of uninstalls accumulated over periods
`reinstalls`	number of reinstalls per period
`reinstalls_total`	number of reinstalls accumulated over periods
`first_uninstalls`	number of first time uninstalls per period
`first_uninstalls_total`	number of first time uninstalls accumulated over periods
`first_reinstalls`	number of first time reinstalls per period
`first_uninstalls_total`	number of first time reinstalls accumulated over periods
`gdpr_forgets`	number of users wanting to be forgotten per period
`gdpr_forgets_total`	number of users wanting to be forgotten accumulated over periods

Note: Cohort KPIs related to deattribution and reattribution only have a meanigfull value when attribution_source=first is selected. For attribution_source=dynamic these events will only show up in the first (0) period, which is the period of the attribution.

Ad Revenue Cohort KPIs

`ad_revenue`	amount of `ad_revenue` per period
`ad_revenue_total`	accumulated `ad_revenue` for this and all previous periods
`ad_revenue_total_in_cohort`	for the Nth period after install, the `ad_revenue` accumulated over all periods from 0 to N, from users who installed at least N periods ago
`ad_impressions`	number of `ad_impressions` generated per period
`ad_impressions_total`	accumulated `ad_impressions` for this and all previous periods
`ad_impressions_total_in_cohort`	for the Nth period after install, the `ad_impressions` accumulated over all periods from 0 to N, from all users who installed at least N periods ago
`all_revenue`	`ad_revenue` plus `revenue`
`all_revenue_total`	`ad_revenue_total` plus `revenue_total`
`all_revenue_per_user`	`all_revenue` divided by `cohort_size`
`all_revenue_total_in_cohort`	`ad_revenue_total_in_cohort` plus `revenue_total_in_cohort`
`ad_rpm`	amount of `ad_revenue` per mille (thousand `ad_impressions`) period, i.e., `ad_revenue / ad_impressions * 1000`

Example

Request:

GET http://api.adjust.com/kpis/v1/2eb2na2w54c3/cohorts?start_date=2015-05-01&end_date=2015-05-31&kpis=sessions&grouping=trackers,periods&period=week

Response:

{
  "result_parameters": {
    "kpis": ["sessions"],
    "start_date": "2015-05-01",
    "end_date": "2015-05-31",
    "sandbox": false,
    "grouping": ["trackers", "periods"],
    "trackers": [
      {
        "token": "foobar",
        "name": "Network 1",
        "has_subtrackers": true
      }
    ],
    "period": "week"
  },
  "result_set": {
    "token": "{your_user_token}",
    "name": "app name",
    "currency": "USD",
    "trackers": [
      {
        "token": "foobar",
        "periods": [
          {
            "period": "0",
            "kpi_values": [4]
          },
          {
            "period": "1",
            "kpi_values": [5]
          }
        ]
      }
    ]
  }
}

Once again, note the correspondence between kpis and kpi_values.

Query Parameters

This section gives more details about each of the API request parameters that you already saw above. Note that the API is descriptive about errors it might find, parsing request parameters. Invalid requests will respond with HTTP 400 errors, detailing the problems in the body.

Time Periods

start_date and end_date specifies the date range filter in the format YYYY-MM-DD. If none is given, the default date range is the current month.

Timezone

The utc_offset query parameter is used to determine a timezone relative to UTC. For example, if you want to see how many installs happened on February 14, 2016, in the Pacific Time Zone (PT), add start_date=2016-02-14&end_date=2016-02-14&utc_offset=-08:00 to your query. The format is utc_offset=[+-]HH:MM, e.g., utc_offset=+04:00. The + is the default offset direction and so can be omitted, but the - must always be included.

Note: If utc_offset is not added, UTC timezone is used.

Reattributed

Using the reattributed query parameter, you can filter KPIs for reattributed users only. Reattribution is when a user who has already installed your app returns to it through a new Adjust-tracked source.

Note: This query can only pull data from timeframes starting on or later than 1 September 2017.

When using this filter in conjunction with the WAU and MAU KPIs, there are some points to bear in mind:

A user cannot be an installed user and a reattributed user simultaneously
- This means that, if a user installs on Monday 1 June and is reattributed on Wednesday 3 June, they will remain an installed WAU user until Sunday 7 June and become a reattributed WAU user for only Monday 8 June and Tuesday 9 June
  - If the user triggers a new app session after June 9, they will return as a reattributed WAU user for seven days
The same logic applies to MAUs but on a monthly timeframe

KPIs

kpis specifies the comma-separated list of requested KPIs that may vary for each of the resources. If the parameter is not given, a default list is assumed. Note the response result_set also returns an array of kpis.

Country

countries specifies a comma-separated list of two-character ISO 3166-1 alpha-2 country codes. If no country-filtering is given, all-countries is assumed.

OS Names

A list of valid os_name values:

android
bada
blackberry
ios
linux
macos
server
symbian
unknown
webos
windows
windows-phone

Device Types

A list of valid device_types values:

bot
console
ipod
mac
pc
phone
server
simulator
tablet
tv
unknown

Human Readable KPIs

One feature that has proven useful to a number of clients, especially when working with the data in CSV, is the human_readable_kpis. Appending the GET param human_readable_kpis=true to any request URL would translate the resulting KPIs, period, etc. headlines into appropriately formatted English. For example, instead of lifetime_value you’d get Lifetime Value. Furthermore, instead of period, the response field will read Weeks after Install, assuming week has been the selected period in a cohorts query.

This facilitates sharing results from the CSV API calls as reports, without having to rename columns or headlines. At the same time, it enables us to support a consistent naming for automated API access and programmatic parsing of the data.

Grouping

grouping specifies a grouping for the dataset. The resulting data will be nested in the exact order as specified. E.g. grouping=trackers,countries will nest per country for each tracker, while grouping=countries,trackers will nest the other way around. You are encouraged to play around with the grouping parameters to get a better feel for it.

Below is a complete list of all acceptable values for the grouping request parameter.

Tracker-Related Grouping

Tracker grouping allows you to break data down by tracker, in line with the tracker tree. Let’s go through some examples:

If you give no parent tracker and grouping=trackers, your data will be grouped by all Network trackers for your app.
If you give no parent tracker and grouping=campaigns, your data will be grouped by all Campaign trackers for your app.
If you give a Campaign parent tracker and grouping=trackers or grouping=adgroups, your data will be grouped by all Adgroup trackers, descendant from the given Campaign parent.
If you give a Campaign parent tracker and grouping=creatives, your data will be grouped by all Creative trackers, descendant from the given Campaign parent.

The complete list of acceptable values:

trackers: will group by network / campaign / adgroup / creative depending on the optionally given tracker_token. See the Trackers Tree section for more on tracker grouping.
networks: will group by network independent of the optionally given tracker_token. The result set will include a networks field holding an array of found networks.
campaigns: will group by network independent of the optionally given tracker_token. The result set will include a campaigns field holding an array of found campaigns.
adgroups: will group by network independent of the optionally given tracker_token. The result set will include an adgroups field holding an array of found adgroups.
creatives: will group by network independent of the optionally given tracker_token. The result set will include a creatives field holding an array of found creatives.

Time-period Grouping

hour: will group by hour. The result set will include a dates field holding an array of applicable hours of the period, where the corresponding date field lists the hour.
day: will group by day. The result set will include a dates field holding an array of applicable days of the period, where the corresponding date field lists the day
week: will group by week. The result set will include a dates field holding an array of applicable weeks, where the corresponding date field lists the start date of the week.
month: will group by month. The result set will include a dates field holding an array of applicable months, where the corresponding date field lists the first of the month.

Note: When using longer date groupings (weeks or months), it is recommended to include entire periods in your date selection. The first date will be rounded to the start of the week or month. If your date selection starts in the middle of a week or month, this group may not be properly comparable to other groups in your result set.

Further Grouping Options

countries: will group by country. The result set will include a countries field holding an array of found countries, where the corresponding country field names the two-character (ISO 3166-1 alpha-2) country code. For a full list of country codes, see the table below.
region: will group by business region, i.e., APAC, EMEA and LATAM. The result will include a region field holding an array of found regions, where the corresponding region field names the region acronym. For a full list of countries and the regions they belong to, click here.
device_types: will group by device type. The result set will include a device_types field holding an array of found device_types, where the corresponding device_type field names the type of device out of the list in the device_types section above.
os_names: will group by OS name. The result set will include an os_names field holding an array of found os_names, where the corresponding os_names field names the operating system of the devices.
partners: will group by partner name. The result set will include a partners field holding an array of found partners, where the corresponding partner field names the partner to which the data belongs.

Trackers Tree

As mentioned, all endpoints could be requested either with or without specifying a tracker token. For each resource above, two endpoints are specified, where the second form specifies a tracker. If you use the second form, the result set will be filtered by the tracker that you provide, and the trackers grouping would segment your result set by subtracker.

If no tracker token is given, data for every network is returned, and the trackers grouping would segment your result set by network-level trackers as an entry in the trackers array.

With the trackers grouping, the result set will contain metadata for each tracker. This metadata includes a has_subtrackers boolean field, which indicates that you could also query the given token to traverse the tree deeper.

For example, if you request a query with a Campaign parent tracker, the response will contain the data grouped by the respective Adgroup subtrackers.

Tracker Filtering

Tracker filtering is useful for handling complicated tracker setups. You can focus your result set to data from specific trackers by using the tracker_filter query parameter with any of your KPI Service queries. This combined with the Grouping options provided by the API create a powerful facility for drilling down into your data while retaining focus on given Networks, Campaigns or Adgroups.

Say x2yiy3 and vi4wwc are two Network tracker-tokens in your Adjust tracker setup. You are able to refine the result set to only contain data belonging to or descending from these two Networks by using the query parameters:

&tracker_filter=x2yiy3,vi4wwc&grouping=network,campaign,adgroup,creative

Note that the grouping parameter is optional. In fact any grouping (or none at all) could give you meaningful results depending on your research goals.

Furthermore, the tracker filtering could be used in combination with the Multiple-Apps-Overview Endpoint, like so:

GET https://api.adjust.com/kpis/v1?app_tokens=44cdcdck2syc,9xmtsnp687ek&tracker_filter=q9y2y2,xi2wxq,x2yiy3,vi4wwc&grouping=app,network,campaign,adgroup,creative

This way you can, for example, compare the performances of the same networks for multiple apps in a single API call.

Multiple-Apps-Overview Endpoint

The endpoints discussed thus far request data for only a single app. These are essential for a full breakdown of an individual app, but will not give you an overview for multiple (or even all) of the apps you track on Adjust. A full overview is made possible with the multiple-apps endpoint, which we discuss here.

Endpoint URL

There are two different endpoints for deliverables that you can call:

GET https://api.adjust.com/kpis/v1{.csv|.json}?app_tokens=44cdcdck2syc,9xmtsnp687ek 
GET https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek{.csv|.json}?

Both endpoints will return the same results.

Regarding cohorts, you would need to use the following endpoint:

https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek/cohorts{.csv|.json}?

Note that, same as with all other endpoints, the .csv or .json extensions are not mandatory here. The default response format is again JSON, but if you need to change it to CSV you are only required to append the .csv extension.

Param Name	Format	Description
`start_date`	YYYY-MM-DD	The start date of the selected period.
`end_date`	YYYY-MM-DD	The end date of the selected period.
`utc_offset`	[+-]HH:MM, e.g. `utc_offset=-05:00` or `utc_offset=10:00`	UTC offset for timezones
`kpis`	string, e.g. `clicks,installs,maus`	Comma-separated list of App KPIs. Any combination of App KPIs is accepted.
`sandbox`	string `true` or `false`	Requests could be issued for Sandbox or Production data. By default, Production is assumed.
`impression_based`	string `true` or `false`	Requests could be issued as click or impression based view. By default, click based is assumed.
`countries`	string, e.g. `de,us`	Comma-separated list of `ISO 3166 alpha-2`country names.
`os_names`	string, e.g. `ios,android`	Comma-separated list of OS names. The list of OS names applies.
`device_types`	string, e.g. `phone,tablet`	Comma-separated list of device types. The list of Device Types applies.
`grouping`	string, e.g. `apps,countries`	Grouping parameters. See below for more details on grouping.
`human_readable_kpis`	boolean	Print the headlines in English formatting (e.g. following appropriate capitalization rules).

App KPIs

It’s worth repeating that for the kpis parameter of this endpoint, you could use the same set of App KPIs as discussed earlier. The following URL examples is valid:

https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions

And for your cohorts:

https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek/cohorts?kpis=converted_users,sessions

This will breakdown install and sessions data over the default period for the two requested apps (that is, the two app tokens).

Multiple-Apps Grouping

By default, the grouping for this endpoint is per-app. You could however group by tracker, or by period or by any combination of these. In particular, the outlines of the Grouping section apply here as well.

Time-series data per app

Here’s an example of how you could obtain time-series data for installs and sessions for each of the two apps.

https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=apps,days

Time-series data for all apps

Now we are able to omit the apps in the grouping and aggregate only by days. This is a great way of quickly reviewing a summary of your entire apps-profile.

https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=days

An example response from this request would be:

date	installs	sessions
2015-12-01	2093	11703
2015-12-02	1124	11211
2015-12-03	5651	5687

Note that this is the tabular response version, i.e. output in CSV format.

Apps and Network Tracker Breakdown

Next we could request installs and sessions data for each of the two apps, aggregated by Network trackers. This would be useful for comparing the performance of different networks across your apps-profile.

https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=apps,networks

And again, an example tabular output from this request:

app_token	app_name	tracker_token	network	installs	sessions
44cdcdck2syc	First App	5aml2f	AdNetwork	40	80
44cdcdck2syc	First App	28kse9	Email Ads	192	292
9xmtsnp687ek	My Other App	16px8z	AnotherNetwork	2001	3001
9xmtsnp687ek	My Other App	21h2o9	Email Ads	17	37

KPI Service Glossary

We have a full list of the KPIs we provide you as well as their definitions and how they are calculated in our handy KPI Service glossary.

On this topic