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.

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

Each of these queries could be done for either all Network trackers setup for the app or for a given parent tracker. Thus each resource has two endpoints: one without 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 diving into the API specs, however, we suggest a quick look at the R client that we developed to complement it. If you are an R user, then you’ll love how straightforward this client makes it to bring your Adjust data into your R session.

Since the concept of trackers is essential to making sense from the API data, we also suggest a refresher on the terminology around trackers. Note in particular the concepts of hierarchical tracker composition from Network, Campaign, Adgroup and Creative components.

N.B. the KPI Service is only available for clients on a Business Pro package or above. You can check out your current pricing package in the dashboard.

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

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. 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 NameFormatDescription
start_dateYYYY-MM-DDThe start date of the selected period.
end_dateYYYY-MM-DDThe end date of the selected period.
utc_offset[+-]HH:MM, e.g. utc_offset=-05:00 or utc_offset=10:00UTC offset for timezones
kpisstring, e.g. clicks,installs,mausComma-separated list of App KPIs. Any combination of App KPIs is accepted.
event_kpisstring, e.g. token1_events,token1_revenue_per_userComma-separated list of Event KPIs. Each KPI should be prefixed with either an event token or all. See below for examples.
reattributedstring true, false, or allFilter KPIs by installed or reattributed users only or by all users (default)
sandboxstring true or falseRequests could be issued for Sandbox or Production data. By default, Production is assumed.
impression_basedstring true or falseRequests could be issued as click or impression based view. By default, click based is assumed.
attribution_typestring click, impression, or allClick, impression, or click and impression combined (this overrides the impression_based parameter)
attribution_sourcestring, first or dynamicDetermines 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.
countriesstring, e.g. de,usComma-separated list of ISO 3166 alpha-2 country names.
os_namesstring, e.g. ios,androidComma-separated list of OS names. Find the valid OS names below.
device_typesstring, e.g. phone,tabletComma-separated list of device types. Find the valid device types below.
groupingstring, e.g. trackers,countriesGrouping parameters. See below for more details on grouping.


App KPIs

The list of supported App KPIs - that you may pass as values to the kpis parameter - is given below.
 
App KPIDescription
clicksNumber of clicks
impressionsNumber of impressions
installsNumber of installs
uninstallsNumber of uninstalls
uninstall_cohortNumber of uninstalls from users who installed within your selected timeframe
reinstallsNumber of reinstalls
click_conversion_rateClick conversion rate (an average of installs/clicks weighted by clicks).
ctrClick through rate (clicks/impressions weighted by impressions).
impression_conversion_rateImpression conversion rate (an average of installs/impressions weighted by impressions).
reattributionsNumber of reattributions
reattribution_reinstallsNumber of reinstalls that also led to a reattribution
deattributionsNumber of deattributions
sessionsNumber of sessions
revenue_eventsNumber of revenue events
revenueTotal revenue (in the app's reporting currency)
cohort_revenueTotal revenue from users who were (re)attributed within your selected timeframe
dausAverage daily active users
wausAverage weekly active users
mausAverage monthly active users
limit_ad_tracking_installsNumber of installs from devices with Limit Ad Tracking enabled
limit_ad_tracking_install_rateProportion of installs from devices with Limit Ad Tracking enabled: limit_ad_tracking_installs/installs
limit_ad_tracking_reattributionsNumber of reattributions from devices with Limit Ad Tracking enabled
limit_ad_tracking_reattribution_rateProportion of installs from devices with Limit Ad Tracking enabled: limit_ad_tracking_reattributions/reattributions
gdpr_forgetsThe 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_revenueTotal ad revenue from users who installed in your selected timeframe
cohort_all_revenuecohort_revenue + cohort_ad_revenue


Fraud KPIs

Fraud KPIs are only available for accounts with the Adjust Fraud Prevention Suite enabled.
 
Fraud KPIDescription
rejected_installsNumber 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_ipNumber of rejected installs due to anonymous IP
rejected_installs_too_many_engagementsNumber of rejected installs due to too many engagements
rejected_installs_distribution_outlierNumber of rejected installs due to distribution outliers
rejected_installs_click_injectionNumber of rejected installs due to engagement injection
rejected_installs_invalid_signatureNumber of rejected installs due to a missing or invalid SDK Signature
rejected_reattributionsNumber 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_ipNumber of rejected reattributions due to anonymous IP
rejected_reattributions_too_many_engagementsNumber of rejected reattributions due to too many engagements
rejected_reattributions_distribution_outlierNumber of rejected reattributions due to distribution outliers
rejected_reattributions_click_injectionNumber rejected reattributions due to engagement injection
rejected_install_rateRejected install rate: rejected_installs/(installs + rejected_installs).
rejected_install_anon_ip_rateRate of rejected installs due to anonymous IP: rejected_installs_anon_ip/(installs + rejected_installs).
rejected_install_too_many_engagements_rateRate of rejected installs due to too many engagements: rejected_installs_too_many_engagements/(installs + rejected_installs).
rejected_install_distribution_outlier_rateRate of rejected installs due to distribution outliers: rejected_installs_distribution_outlier/(installs + rejected_installs).
rejected_install_click_injection_rateRate of rejected installs due to engagement injection: rejected_installs_click_injection/(installs + rejected_installs)
rejected_reattribution_rateRejected reattributions rate: rejected_reattributions/(reattributions + rejected_reattributions).
rejected_reattribution_anon_ip_rateRate of rejected reattributions due to anonymous IP: rejected_reattributions_anon_ip/(reattributions + rejected_reattributions).
rejected_reattribution_too_many_engagements_rateRate of rejected reattributions due to too many engagements: rejected_reattributions_too_many_engagements/(reattributions + rejected_reattributions).
rejected_reattribution_distribution_outlier_rateRate of rejected reattributions due to distribution outliers: rejected_reattributions_distribution_outlier/(reattributions + rejected_reattributions).
rejected_reattribution_click_injection_rateRate 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 KPIDescription
install_costInstall cost
click_costClick cost
impression_costImpression cost
costThe sum of click_cost + impression_cost + install_cost
paid_installsThe number of installs, for which there is cost data
paid_clicksThe number of clicks, for which there is cost data
paid_impressionsThe number of impressions, for which there is cost data
ecpcEffective cost per click, i.e. cost / paid_clicks
ecpmEffective cost per mille (thousand impressions), i.e. cost / paid_impressions * 1000
ecpiEffective cost per install, i.e. cost / paid_installs
cohort_gross_profitThe gross profit, i.e. cohort_revenue - cost
return_on_investmentThe ROI metric derived by cohort_gross_profit / cost
revenue_to_costThe revenue-to-cost ratio derived by cohort_revenue / cost
roasReturn on ad spend, the ROA metric derived by cohort_ad_revenue / cost
Note: costs are returned in millicents, i.e. 5.45661 Euros would return cost=545661
 

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 KPIDescription
revenue_eventsNumber of revenue events
revenueTotal revenue in the app's reporting currency
eventsNumber of events
first_eventsNumber 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_eventTotal revenue divided by number of events
revenue_per_revenue_eventTotal 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 NameFormatDescription
start_dateYYYY-MM-DDThe start date of the selected period
end_dateYYYY-MM-DDThe end date of the selected period
utc_offset&[+-]HH:MM, e.g. utc_offset=-05:00 or utc_offset=10:00UTC offset for timezones
kpisstring, e.g. revenue_events,revenueComma-separated list of Event KPIs. Any combination of Event KPIs is accepted.
sandboxstring true or falseRequests could be issued for Sandbox or Production data. By default, Production is assumed.
eventsstring, e.g. event_token1,event_token2Comma-separated list of Event Tokens. You’ll find the Event Tokens for your events in the Adjust dashboard.
attribution_typestring click, impression, or allClick, impression, or click and impression combined (this overrides the impression_based parameter)
attribution_sourcestring, first or dynamicDetermines 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.
countriesstring, e.g. de,usComma-separated list of ISO 3166 alpha-2 country names
os_namesstring, e.g. ios,androidComma-separated list of OS names. Find the valid OS names below.
device_typesstring, e.g. phone,tabletComma-separated list of device types. Find the valid device types below.
partner_idsinteger, e.g., 1234,789Comma-separated list of partner IDs. Only data from trackers belonging to these partners will be shown.
groupingstring, e.g. trackers,countriesGrouping 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 NameFormatDescription
start_dateYYYY-MM-DDThe start date of the selected period
end_dateYYYY-MM-DDThe end date of the selected period
utc_offset[+-]HH:MM, e.g. utc_offset=-05:00 or utc_offset=10:00UTC offset for timezones
kpisstring, e.g. revenue_events,revenueComma-separated list of App KPIs. Any combination of App KPIs is accepted.
sandboxstring true or falseRequests could be issued for Sandbox or Production data. By default, Production is assumed.
attribution_typestring click, impression, or allClick, impression, or click and impression combined (this overrides the impression_based parameter)
attribution_sourcestring, first or dynamicDetermines 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.
periodone of day/week/monthThe cohort period
reattributedone of true/false/allControl whether cohort is based on reattributions (true or false). Default value, all, includes both reattributions and installs. Data available from October 1 2016
eventsstring, e.g. abcdef,12345Comma-separated list of event tokens
countriesstring, e.g. de,usComma-separated list of ISO 3166 alpha-2 country names
os_namesstring, e.g. ios,androidComma-separated list of OS names. Find the valid OS names below.
device_typesstring, e.g. phone,tabletComma-separated list of device types. Find the valid device types below.
groupingstring, e.g. trackers,install_dateGrouping 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 KPIDescription
retained_usersnumber of users that came back in period
cohort_sizefor the N-th period-after-install, the number of users who installed at least N periods ago
retention_rateretained_users divided by cohort_size
reattributionsnumber of reattributed users per period
deattributionsnumber of deattributed (i.e., reattributed away from their install tracker) users per period
sessionsnumber of sessions generated per period
sessions_per_usernumber of sessions divided by retained_users
uninstallsnumber of uninstalls per period
uninstalls_totalnumber of uninstalls across all periods
reinstallsnumber of reinstalls per period
reinstalls_totalnumber of reinstalls across all periods
revenueamount of revenue per period
revenue_totalaccumulated revenue for this and all previous periods
revenue_per_userrevenue divided by cohort_size
revenue_per_paying_userrevenue divided by paying_user_size
revenue_total_in_cohortfor 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
lifetime_valuerevenue_total_in_cohortdivided by cohort_size
paying_user_lifetime_valuerevenue_total_in_cohortdivided by paying_user_size
time_spentthe sum of time (in seconds) users spent in period,
time_spent_per_usertime_spent divided by cohort_size
time_spent_per_sessiontime_spent divided by sessions *
paying_usersthe number of paying users in period
paying_user_sizefor the N-th period-after-install, the number of paying users who installed at least N periods ago
paying_users_retention_ratepaying_users divided by retained_users
paying_user_ratepaying_users divided by cohort_size
revenue_eventsthe number of revenue events per period
revenue_events_total_in_cohortfor 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
revenue_events_per_userrevenue_events divided by cohort_size
revenue_events_per_active_userrevenue_events divided by retained_users
revenue_events_per_paying_userrevenue_events divided by paying_users
converted_usersfor 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_sizefor the N-th period-after-install, the number of converted users who installed at least N periods ago
conversion_distributionconverted_users divided by converted_user_size
conversion_per_userconverted_users divided by cohort_size
conversion_per_active_userconverted_users divided by retained_users
eventsnumber of events triggered in period
events_per_converted_userevents divided by converted_users
events_per_userevents divided by cohort_size
events_per_active_userevents divided by retained_users
ad_revenueamount of ad_revenue per period
ad_revenue_totalaccumulated ad_revenue for this and all previous periods
ad_revenue_total_in_cohortfor 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_impressionsnumber of ad_impressions generated per period
ad_impressions_totalaccumulated ad_impressions for this and all previous periods
ad_impressions_total_in_cohortfor 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_revenuead_revenue plus revenue
all_revenue_totalad_revenue_total plus revenue_total
all_revenue_per_userall_revenue divided by cohort_size
all_revenue_total_in_cohortad_revenue_total_in_cohort plus revenue_total_in_cohort
ad_rpmamount of ad_revenue per mille (thousand ad_impressions) period, i.e., ad_revenue / ad_impressions * 1000

*For day 0, week 0, or month 0 cohort calculations, ensure you subtract any install sessions


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 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. If nothing is given, the account’s default timezone will be used. The format is utc_offset=[+-]HH:MM, e.g., utc_offset=+04:00, but the + can be omitted, as it is the default offset direction. The - must always be included.


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 NameFormatDescription
start_dateYYYY-MM-DDThe start date of the selected period.
end_dateYYYY-MM-DDThe end date of the selected period.
utc_offset[+-]HH:MM, e.g. utc_offset=-05:00 or utc_offset=10:00UTC offset for timezones
kpisstring, e.g. clicks,installs,mausComma-separated list of App KPIs. Any combination of App KPIs is accepted.
sandboxstring true or falseRequests could be issued for Sandbox or Production data. By default, Production is assumed.
impression_basedstring true or falseRequests could be issued as click or impression based view. By default, click based is assumed.
countriesstring, e.g. de,usComma-separated list of ISO 3166 alpha-2country names.
os_namesstring, e.g. ios,androidComma-separated list of OS names. The list of OS names applies.
device_typesstring, e.g. phone,tabletComma-separated list of device types. The list of Device Types applies.
groupingstring, e.g. apps,countriesGrouping parameters. See below for more details on grouping.
human_readable_kpisbooleanPrint 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:
 
dateinstallssessions
2015-12-01209311703
2015-12-02112411211
2015-12-0356515687

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_tokenapp_nametracker_tokennetworkinstallssessions
44cdcdck2sycFirst App5aml2fAdNetwork4080
44cdcdck2sycFirst App28kse9Email Ads192292
9xmtsnp687ekMy Other App16px8zAnotherNetwork20013001
9xmtsnp687ekMy Other App21h2o9Email Ads1737


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