Languages 

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

App KPIs

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

Fraud KPIs

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

Cost KPIs

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

Note: All cost KPIs are rounded to two decimal digits, except ecpc, ecpm, and ecpi, which are rounded to four decimal digits. For example, 5.45661 euros would return cost=5.46 when rounded to two decimal digits.

Ad Revenue KPIs

Ad Revenue KPIs are only available for accounts with Ad Revenue enabled.

Ad Revenue KPIDescription
ad_revenueTotal revenue (in the app's reporting currency) from ad_impressions
ad_impressionsNumber of ad_impressions
ad_rpmad_revenue per mille (thousand impressions), that is,  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.

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.

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. There is no limit for months. 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.

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

Note: Cohort KPIs related to deattribution and reattribution only have a meaningful 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

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: if the tracker_token is present, then results will be grouped by networks scoped by that tracker token. If the tracker_token is not present, then results will be grouped by all networks. If the response type is JSON, the result set will include a networks field holding an array of found networks.
  • campaigns: if the tracker_token is present, then results will be grouped by campaigns scoped by that tracker token. If the tracker_token is not present, then the results will be grouped by all campaigns. If the response type is JSON, the result set will include a campaigns field holding an array of found campaigns.
  • adgroups: if the tracker_token is present, then results will be grouped by adgroups scoped by that tracker token. If the tracker_token is not present, then the results will be grouped by all adgroups. If the response type is JSON, the result set will include an adgroups field holding an array of found adgroups.
  • creatives: if the tracker_token is present, then results will be grouped by creatives scoped by that tracker token. If the tracker_token is not present, then the results will be grouped by all creatives. If the response type is JSON, 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

For the trackers grouping, if tracker_token is present, then the results will be grouped by the trackers on the level immediately under the tracker_token. For example, if your query has a campaign tracker_token, the response will be grouped by the adgroup trackers under it. If tracker_token is not present, then the results will be grouped by all networks.

With the trackers grouping, if the response type is JSON, 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.

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.

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.