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.

1Versioning

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.

2Response 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.

3Authentication

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.

4App 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.

5Overview 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.

5.1Endpoints

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}

5.2Query 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.
grouping string, e.g. trackers,countries Grouping parameters. See below for more details on grouping.

5.3App 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).
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)
cohort_revenue Total revenue from users who installed 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 reattributions 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.

5.4Fraud 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)

5.5Cost KPIs

Cost KPIs are 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
revenue_to_cost The revenue-to-cost ratio derived by cohort_revenue/cost

note: costs are returned in millicents. i.e. 5.45661 Euros would return cost=545661

5.6Event 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.

5.7Facilitation 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.

5.8Examples

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.

5.9KPI 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.

6Event Queries

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

6.1Endpoints

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}

6.2Query 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.

6.3Event 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.

6.4Example

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.

7Cohort 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 or the like. This allows you to retrieve cohort-based KPIs such as retention by day after install. Please refer to our guide to cohort analysis.

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.

7.1Endpoints

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

7.2Query 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 EventTokens.
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.

7.3Cohort 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
reattributions number of reattributed users per period
deattributions number of deattributed (i.e., reattributed away from their install tracker) users per period
sessions number of sessions generated per period
sessions_per_user number of sessions divided by retained_users
uninstalls number of uninstalls per period
uninstalls_total number of uninstalls across all periods
reinstalls number of reinstalls per period
reinstalls_total number of reinstalls across all periods
revenue amount of revenue per period
revenue_total accumulated revenue 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
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_total_in_cohort accumulated revenue events for this and all previous periods
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

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

7.4Example

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.

8Query 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.

8.1Time 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.

8.2Timezone

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.

8.3Reattributed

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

8.4KPIs

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.

8.5Country

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.

8.6OS Names

A list of valid os_names values:

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

8.7Device Types

A list of valid device_types values:

bot
console
ipod
mac
pc
phone
server
simulator
tablet
unknown

8.8Human 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.

9Grouping

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 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.

9.2Time-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.

9.3Further 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_name 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.

10Trackers 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.

11Tracker 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.

12Multiple-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.

12.1Endpoint 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).

12.2App 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=install,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).

12.3Multiple-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

13KPI 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.