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 Name | Format | Description |
start_date | YYYY-MM-DD | The start date of the selected period. |
end_date | YYYY-MM-DD | The end date of the selected period. |
utc_offset | [+-]HH:MM, e.g. utc_offset=-05:00 or utc_offset=10:00 | UTC offset for timezones |
kpis | string, e.g. clicks,installs,maus | Comma-separated list of App KPIs. Any combination of App KPIs is accepted. |
event_kpis | string, e.g. token1_events,token1_revenue_per_user | Comma-separated list of Event KPIs. Each KPI should be prefixed with either an event token or all . See below for examples. |
reattributed | string true , false , or all | Filter KPIs by installed or reattributed users only or by all users (default) |
sandbox | string true or false | Requests could be issued for Sandbox or Production data. By default, Production is assumed. |
impression_based | string true or false | Requests could be issued as click or impression based view. By default, click based is assumed. |
attribution_type | string click , impression , or all | Click, impression, or click and impression combined (this overrides the impression_based parameter) |
attribution_source | string, first or dynamic | Determines whether in-app activity is assigned to the user’s install source (first ) or divided among the install source and subsequent sources of reattribution (dynamic ). The default setting is dynamic . |
countries | string, e.g. de,us | Comma-separated list of ISO 3166 alpha-2 country names. |
os_names | string, e.g. ios,android | Comma-separated list of OS names. Find the valid OS names below. |
device_types | string, e.g. phone,tablet | Comma-separated list of device types. Find the valid device types below. |
regions | string, e.g., APAC, EMEA | Comma-separated list of standard or account-specific business regions. Add + or - before the region name to include (default) or exclude it. |
grouping | string, e.g. trackers,countries | Grouping parameters. See below for more details on grouping. |
cohort_revenue_period | string, e.g 15d , [1d-30d , 60d , 90d , 120d ] | Result should only sum up revenue of the first n days after attribution. |
App KPIs
The list of supported App KPIs - that you may pass as values to the kpis
parameter - is given below.App KPI | Description |
clicks | Number of clicks |
impressions | Number of impressions |
installs | Number of installs |
uninstalls | Number of uninstalls |
uninstall_cohort | Number of uninstalls from users who installed within your selected timeframe |
reinstalls | Number of reinstalls |
click_conversion_rate | Click conversion rate (an average of installs /clicks weighted by clicks ). |
ctr | Click through rate (clicks /impressions weighted by impressions ). |
impression_conversion_rate | Impression conversion rate (an average of installs /impressions weighted by impressions ). |
reattributions | Number of reattributions |
reattribution_reinstalls | Number of reinstalls that also led to a reattribution |
deattributions | Number of deattributions |
sessions | Number of sessions |
revenue_events | Number of revenue events |
revenue | Total revenue (in the app's reporting currency) |
all_revenue | revenue + ad_revenue |
cohort_revenue | Total revenue from users who were (re)attributed within your selected timeframe |
daus | Average daily active users |
waus | Average weekly active users |
maus | Average monthly active users |
limit_ad_tracking_installs | Number of installs from devices with Limit Ad Tracking enabled |
limit_ad_tracking_install_rate | Proportion of installs from devices with Limit Ad Tracking enabled: limit_ad_tracking_installs /installs |
limit_ad_tracking_reattributions | Number of reattributions from devices with Limit Ad Tracking enabled |
limit_ad_tracking_reattribution_rate | Proportion of installs from devices with Limit Ad Tracking enabled: limit_ad_tracking_reattributions /reattributions |
gdpr_forgets | The total number of users who have exercised their right to be forgotten. Adjust permanently deletes the historical personal data for all of these users but retains their aggregated data for dashboard reporting. Their device data will no longer be received by Adjust or appear anywhere in the Adjust dashboard in the future. |
cohort_ad_revenue | Total ad revenue from users who installed in your selected timeframe |
cohort_all_revenue | cohort_revenue + cohort_ad_revenue |
Fraud KPIs
Fraud KPIs are only available for accounts with the Adjust Fraud Prevention Suite enabled.Fraud KPI | Description |
rejected_installs | Number of rejected installs. This is the sum of rejected_installs_anon_ip + rejected_installs_too_many_engagements + rejected_installs_distribution_outlier + rejected_installs_click_injection |
rejected_installs_anon_ip | Number of rejected installs due to anonymous IP |
rejected_installs_too_many_engagements | Number of rejected installs due to too many engagements |
rejected_installs_distribution_outlier | Number of rejected installs due to distribution outliers |
rejected_installs_click_injection | Number of rejected installs due to engagement injection |
rejected_installs_invalid_signature | Number of rejected installs due to a missing or invalid SDK Signature |
rejected_reattributions | Number of rejected reattributions. This is the sum of rejected_reattributions_anon_ip + rejected_reattributions_too_many_engagements + rejected_reattributions_distribution_outlier + rejected_reattributions_click_injection |
rejected_reattributions_anon_ip | Number of rejected reattributions due to anonymous IP |
rejected_reattributions_too_many_engagements | Number of rejected reattributions due to too many engagements |
rejected_reattributions_distribution_outlier | Number of rejected reattributions due to distribution outliers |
rejected_reattributions_click_injection | Number rejected reattributions due to engagement injection |
rejected_install_rate | Rejected install rate: rejected_installs /( |
| Rate of rejected installs due to anonymous IP: rejected_installs_anon_ip /(installs + rejected_installs ). |
| Rate of rejected installs due to too many engagements: rejected_installs_too_many_engagements /(installs + rejected_installs ). |
| Rate of rejected installs due to distribution outliers: rejected_installs_distribution_outlier /(installs + rejected_installs ). |
| Rate of rejected installs due to engagement injection: rejected_installs_click_injection /(installs + rejected_installs ) |
| Rejected reattributions rate: rejected_reattributions /(reattributions + rejected_reattributions ). |
| Rate of rejected reattributions due to anonymous IP: rejected_reattributions_anon_ip /(reattributions + rejected_reattributions ). |
| Rate of rejected reattributions due to too many engagements: rejected_reattributions_too_many_engagements /(reattributions + rejected_reattributions ). |
| Rate of rejected reattributions due to distribution outliers: rejected_reattributions_distribution_outlier /(reattributions + rejected_reattributions ). |
| Rate of rejected reattributions due to engagement injection: rejected_reattributions_click_injection /(reattributions + rejected_reattributions ) |
Cost KPIs
Cost KPIs are only available for accounts with cost data enabled.Cost KPI | Description |
install_cost | Install cost |
click_cost | Click cost |
impression_cost | Impression cost |
cost | The sum of click_cost + impression_cost + install_cost |
paid_installs | The number of installs, for which there is cost data |
paid_clicks | The number of clicks, for which there is cost data |
paid_impressions | The number of impressions, for which there is cost data |
ecpc | Effective cost per click, i.e. cost / paid_clicks |
ecpm | Effective cost per mille (thousand impressions), i.e. cost / paid_impressions * 1000 |
ecpi | Effective cost per install, i.e. cost / paid_installs |
cohort_gross_profit | The gross profit, i.e. cohort_revenue - cost |
return_on_investment | The ROI metric derived by cohort_gross_profit / cost |
rcr | The revenue-to-cost ratio derived by cohort_revenue / cost |
roas | Return on ad spend, the ROA metric derived by cohort_ad_revenue/cost *100 |
Ad Revenue KPIs
Ad Revenue KPI | Description |
ad_revenue | Total revenue (in the app's reporting currency) from ad_impressions |
ad_impressions | Number of ad_impressions |
ad_rpm | ad_revenue per mille (thousand impressions), i.e. ad_revenue / ad_impressions * 1000 |
Event KPIs
See the list of supported Event KPIs that you can pass, prepended with anevent_token
, to the event_kpis
parameter on an Overview request. These Event KPIs are also used on Events
requests as discussed in the Events section.Event KPI | Description |
revenue_events | Number of revenue events |
revenue | Total revenue in the app's reporting currency |
events | Number of events |
first_events | Number of events triggered for the first time by a user. Think about first_events to events the way you would think about installs to sessions ! |
revenue_per_event | Total revenue divided by number of events |
revenue_per_revenue_event | Total revenue divided by number of revenue events |
Facilitation for Event KPI requests
This section is only relevant if you plan to request event_kpis with your Overview requests. In the other case, you may skip reading this.
Specifying the event_kpis individually may rapidly result in very long parameters. For example, the below is a valid value for event_kpis:
event_kpis=token1_events,token2_events,token1_revenue,token2_revenue
For this reason, some shortcuts are supported. This string:
event_kpis=token1_revenue|events|revenue_per_event
is equivalent to
event_kpis=token1_revenue,token1_events,token1_revenue_per_event
Furthermore, the special keyword all
can be used to expand to all defined events. For example, if you have two events with tokens token1
and token2
, the value:
event_kpis=all_revenue|events|revenue_per_event
would be equivalent to
event_kpis=token1_revenue,token1_events,token1_revenue_per_event,token2_revenue,token2_events,token2_revenue_per_event
Finally, this string:
event_kpis=all_revenue,all_events,all_revenue_per_event
would be equivalent to
event_kpis=token1_revenue,token2_revenue,token1_events,token2_events,token1_revenue_per_event,token2_revenue_per_event
Note that the difference between the last two formats is how the order of the metrics is determined. More on that below.
Examples
Requesting only App KPIs
Request:
GET http://api.adjust.com/kpis/v1/2eb2na2w54c3?start_date=2015-05-01&end_date=2015-05-31&kpis=sessions,installs&countries=de,gb
Response:
{ "result_parameters": { "kpis": ["sessions", "installs"], "start_date": "2015-05-01", "end_date": "2015-05-31", "sandbox": false, "countries": ["de", "gb"], "trackers": [ { "token": "foobar", "name": "Network 1", "has_subtrackers": true }, { "token": "15jvui", "name": "Network 2", "has_subtrackers": true } ], "grouping": ["trackers"] }, "result_set": { "token": "2eb2na2w54c3", "name": "app name", "currency": "USD", "trackers": [ { "token": "foobar", "kpi_values": [100, 299] }, { "token": "15jvui", "kpi_values": [557, 880] } ] } }
Notice the one-to-one correspondence between the kpis
array in the result_parameters
and the kpi_values
arrays in result_set
. The tracker Network 1
in this response has for example 100 sessions
and 299 installs
.
Requesting App and Event KPIs
In addition to the kpis
parameter, you can also request Event KPIs using the event_kpis
parameter.
Request:
GET http://api.adjust.com/kpis/v1/2eb2na2w54c3?start_date=2015-05-01&end_date=2015-05-31&kpis=clicks&event_kpis=token1_events,token1_revenue&countries=de,gb
Response:
{ "result_parameters": { "kpis": ["clicks", "token1_events", "token1_revenue"], "start_date": "2015-05-01", "end_date": "2015-05-31", "sandbox": false, "countries": ["de", "gb"], "trackers": [ { "token": "foobar", "name": "Network 1", "has_subtrackers": true }, { "token": "15jvui", "name": "Network 2", "has_subtrackers": true } ], "events":[ { "name": "YourEventName", "token": "token1" } ], "grouping": ["trackers"] }, "result_set": { "token": "2eb2na2w54c3", "name": "app name", "currency": "USD", "trackers": [ { "token": "foobar", "kpi_values": [221, 100, 299.30] }, { "token": "15jvui", "kpi_values": [1005, 557, 880.75] } ] } }
Notice the one-to-one correspondence between the kpis
array in the result_parameters
and the kpi_values
arrays in result_set
. Thus the tracker Network 1
in this response has 221 clicks, 100 occurrences of events with token token1
and 299.30 revenue from those events.
KPI Ordering
Note that the order in which you request kpis
and/or event_kpis
determines the order of the response you’ll receive. The latter example above illustrates this.
This KPI ordering might be especially useful when you request csv
data from the API. In this case, the columns of the response would exactly match the way you request the KPIs.
Event Queries
This section deals with Event KPI queries. These endpoints are useful if you want data grouped by events.
Endpoints
GET https://api.adjust.com/kpis/v1/:app_token/events{.csv|.json} GET https://api.adjust.com/kpis/v1/:app_token/trackers/:tracker_token/events{.csv|.json}
Query Parameters
A list of supported query parameters is given here; see also the details on expected parameter values.
Param Name | Format | Description |
start_date | YYYY-MM-DD | The start date of the selected period |
end_date | YYYY-MM-DD | The end date of the selected period |
utc_offset | &[+-]HH:MM, e.g. utc_offset=-05:00 or utc_offset=10:00 | UTC offset for timezones |
kpis | string, e.g. revenue_events,revenue | Comma-separated list of Event KPIs. Any combination of Event KPIs is accepted. |
sandbox | string true or false | Requests could be issued for Sandbox or Production data. By default, Production is assumed. |
events | string, e.g. event_token1,event_token2 | Comma-separated list of Event Tokens. You’ll find the Event Tokens for your events in the Adjust dashboard. |
attribution_type | string click , impression , or all | Click, impression, or click and impression combined (this overrides the impression_based parameter) |
attribution_source | string, first or dynamic | Determines whether in-app activity is assigned to the user’s install source (first ) or divided among the install source and subsequent sources of reattribution (dynamic ). The default setting is dynamic . |
countries | string, e.g. de,us | Comma-separated list of ISO 3166 alpha-2 country names |
os_names | string, e.g. ios,android | Comma-separated list of OS names. Find the valid OS names below. |
device_types | string, e.g. phone,tablet | Comma-separated list of device types. Find the valid device types below. |
partner_ids | integer, e.g., 1234,789 | Comma-separated list of partner IDs. Only data from trackers belonging to these partners will be shown. |
grouping | string, e.g. trackers,countries | Grouping parameters. See below for more details on grouping. |
Event KPIs
The list of Event KPIs remains the same as above. However, note that unlike Overview
queries, in the Events
requests you don’t prefix the Event KPIs with an event token. If you want data for specific events, use the events parameter to supply their event tokens.
Example
Request:
GET http://api.adjust.com/kpis/v1/2eb2na2w54c3/events?start_date=2015-05-01&end_date=2015-05-31&kpis=revenue,events,revenue_per_event&grouping=trackers,weeks,events&countries=de,gb
Response:
{ "result_parameters": { "kpis": ["revenue", "events", "revenue_per_event"], "start_date": "2015-05-01", "end_date": "2015-05-31", "sandbox": false, "countries": ["de", "gb"], "events": [{"token": "abcdef","name": "Login"}, {"token": "badcfe","name": "Level Up"}], "grouping": ["trackers", "weeks", "events"], "trackers": [ { "token": "foobar", "name": "Network 1", "has_subtrackers": true } ] }, "result_set": { "token": "2eb2na2w54c3", "name": "app name", "currency": "USD", "trackers": [ { "token": "foobar", "dates": [ { "date": "2015-05-02", "events": [ { "token": "abcdef", "kpi_values": [4, 5, 0.8] }, { "token": "badcfe", "kpi_values": [3, 5, 7.2] } ] }, { "date": "2015-05-09", "events": [ { "token": "badcfe", "kpi_values": [4, 5, 0.8] } ] } ] } ] } }
Note the one-to-one correspondence between the kpis
array in the result_parameters
and the kpi_values
in the result_set
. In this response, the event “Login” has been recorded 5 times with a revenue_per_event
of 0.8.
Cohort Queries
Cohort queries allow you to query data that has been aggregated by user cohort, e.g. a date on which the user has installed/made a purchase/registered etc. This allows you to retrieve cohort-based KPIs such as retention by day after install.Cohorts should be denominated by cohort period and KPI base. The period describes the segmentation depth of the data, either showing weekly cohorts (e.g. users who installed in a given day, week or month) and KPIs based on this period (e.g. retention by day, week, or month after install). The KPI base defines the user subset between all users, paying users (who have triggered at least one revenue event), and users who have triggered an arbitrary event.
As of May 1st, 2019, we offer support for cohort queries up to 120 days and 52 weeks. You can run a cohort query for a specific day, for a range of days (or both), or a specific week or range of weeks using the cohort_period_filter placeholder.
To query a specific day (for example, the 30th day after install), use the format
cohort_period_filter=30
To query a range of days (for example, the first 30 days after install), use the format
cohort_period_filter=0-30
To query both a specific day and a range of days simultaneously (for example, the first 30 days after install and day 120), use the format
cohort_period_filter=0-30,120
To query a specific week (for example, the 10th week after install), use the format
cohort_period_filter=10&period=week
To query a range of weeks (for example, the first ten weeks after install), use the format
cohort_period_filter=0-10&period=week
Endpoints
GET /kpis/v1/:app_token/cohorts{.csv|.json} GET /kpis/v1/:app_token/trackers/:tracker_token/cohorts{.csv|.json}
Query Parameters
A list of supported query parameters is given here; see also the details on expected parameter values.
Param Name | Format | Description |
start_date | YYYY-MM-DD | The start date of the selected period |
end_date | YYYY-MM-DD | The end date of the selected period |
utc_offset | [+-]HH:MM, e.g. utc_offset=-05:00 or utc_offset=10:00 | UTC offset for timezones |
kpis | string, e.g. revenue_events,revenue | Comma-separated list of App KPIs. Any combination of App KPIs is accepted. |
sandbox | string true or false | Requests could be issued for Sandbox or Production data. By default, Production is assumed. |
attribution_type | string click , impression , or all | Click, impression, or click and impression combined (this overrides the impression_based parameter) |
attribution_source | string, first or dynamic | Determines whether in-app activity is assigned to the user’s install source (first ) or divided among the install source and subsequent sources of reattribution (dynamic ). The default setting is dynamic . |
period | one of day /week /month | The cohort period |
reattributed | one of true /false /all | Control whether cohort is based on reattributions (true or false ). Default value, all , includes both reattributions and installs. Data available from October 1 2016 |
events | string, e.g. abcdef,12345 | Comma-separated list of event tokens |
countries | string, e.g. de,us | Comma-separated list of ISO 3166 alpha-2 country names |
os_names | string, e.g. ios,android | Comma-separated list of OS names. Find the valid OS names below. |
device_types | string, e.g. phone,tablet | Comma-separated list of device types. Find the valid device types below. |
grouping | string, e.g. trackers,install_date | Grouping parameters. See below for more details on grouping. |
Note: The time periods used for the
period
query parameter are measured by hours after install, not calendar days. This means if a user installs at 12:47 on a Wednesday, week 0 for that user will conclude at 12:47 the following Wednesday (168 hours later), and month 0 will conclude at 12:47 30 days (720 hours) later.
Cohort KPIs
Cohort KPI | Description |
---|---|
retained_users | number of users that came back in period |
cohort_size | for the N-th period-after-install, the number of users who installed at least N periods ago |
retention_rate | retained_users divided by cohort_size |
sessions | number of sessions generated per period |
sessions_per_user | number of sessions divided by retained_users |
revenue | amount of revenue per period |
revenue_total | accumulated revenue for this and all previous periods |
revenue_events_total | accumulated number of revenue_events for this and all previous periods |
revenue_per_user | revenue divided by cohort_size |
revenue_per_paying_user | revenue divided by paying_user |
revenue_total_in_cohort | for the N-th period-after-install, the revenue accumulated over all periods from 0 to N, from users who installed at least N periods ago |
revenue_events_total_in_cohort | for the N-th period-after-install, the number of revenue_events accumulated over all periods from 0 to N, from users who installed at least N periods ago |
lifetime_value | revenue_total_in_cohort divided by cohort_size |
paying_user_lifetime_value | revenue_total_in_cohort divided by paying_user_size |
time_spent | the sum of time (in seconds) users spent in period, |
time_spent_per_user | time_spent divided by cohort_size |
time_spent_per_session | time_spent divided by sessions * |
paying_users | the number of paying users in period |
paying_user_size | for the N-th period-after-install, the number of paying users who installed at least N periods ago |
paying_users_retention_rate | paying_users divided by retained_users |
paying_user_rate | paying_users divided by cohort_size |
revenue_events | the number of revenue events per period |
revenue_events_per_user | revenue_events divided by cohort_size |
revenue_events_per_active_user | revenue_events divided by retained_users |
revenue_events_per_paying_user | revenue_events divided by paying_users |
converted_users | for the N-th period-after-install, the number of unique users who triggered the given event/events. One user might contribute to multiple days-after-install. |
converted_user_size | for the N-th period-after-install, the number of converted users who installed at least N periods ago |
conversion_distribution | converted_users divided by converted_user_size |
conversion_per_user | converted_users divided by cohort_size |
conversion_per_active_user | converted_users divided by retained_users |
events | number of events triggered in period |
events_per_converted_user | events divided by converted_users |
events_per_user | events divided by cohort_size |
events_per_active_user | events divided by retained_users |
reattributions | number of reattributions generated per period |
deattributions | number of deattributions (first time reattribution) generated per period |
reattributions_per_user | reattributions divided by cohort_size |
deattributions_per_user | deattributions divided by cohort_size |
reattributions_per_deattribution | reattributions divided by deattributions |
uninstalls | number of uninstalls per period |
uninstalls_total | number of uninstalls accumulated over periods |
reinstalls | number of reinstalls per period |
reinstalls_total | number of reinstalls accumulated over periods |
first_uninstalls | number of first time uninstalls per period |
first_uninstalls_total | number of first time uninstalls accumulated over periods |
first_reinstalls | number of first time reinstalls per period |
first_uninstalls_total | number of first time reinstalls accumulated over periods |
gdpr_forgets | number of users wanting to be forgotten per period |
gdpr_forgets_total | number of users wanting to be forgotten accumulated over periods |
Note: Cohort KPIs related to deattribution and reattribution only have a meanigfull value when
attribution_source=first
is selected. For attribution_source=dynamic
these events will only show up in the first (0) period, which is the period of the attribution.
Ad Revenue Cohort KPIs
ad_revenue | amount of ad_revenue per period |
ad_revenue_total | accumulated ad_revenue for this and all previous periods |
ad_revenue_total_in_cohort | for the Nth period after install, the ad_revenue accumulated over all periods from 0 to N, from users who installed at least N periods ago |
ad_impressions | number of ad_impressions generated per period |
ad_impressions_total | accumulated ad_impressions for this and all previous periods |
ad_impressions_total_in_cohort | for the Nth period after install, the ad_impressions accumulated over all periods from 0 to N, from all users who installed at least N periods ago |
all_revenue | ad_revenue plus revenue |
all_revenue_total | ad_revenue_total plus revenue_total |
all_revenue_per_user | all_revenue divided by cohort_size |
all_revenue_total_in_cohort | ad_revenue_total_in_cohort plus revenue_total_in_cohort |
ad_rpm | amount of ad_revenue per mille (thousand ad_impressions ) period, i.e., ad_revenue / ad_impressions * 1000 |
Example
Request:
GET http://api.adjust.com/kpis/v1/2eb2na2w54c3/cohorts?start_date=2015-05-01&end_date=2015-05-31&kpis=sessions&grouping=trackers,periods&period=week
Response:
{ "result_parameters": { "kpis": ["sessions"], "start_date": "2015-05-01", "end_date": "2015-05-31", "sandbox": false, "grouping": ["trackers", "periods"], "trackers": [ { "token": "foobar", "name": "Network 1", "has_subtrackers": true } ], "period": "week" }, "result_set": { "token": "{your_user_token}", "name": "app name", "currency": "USD", "trackers": [ { "token": "foobar", "periods": [ { "period": "0", "kpi_values": [4] }, { "period": "1", "kpi_values": [5] } ] } ] } }
Once again, note the correspondence between kpis
and kpi_values
.
Query Parameters
This section gives more details about each of the API request parameters that you already saw above. Note that the API is descriptive about errors it might find, parsing request parameters. Invalid requests will respond with HTTP 400
errors, detailing the problems in the body.
Time Periods
start_date
and end_date
specifies the date range filter in the format YYYY-MM-DD
. If none is given, the default date range is the current month.
Timezone
The utc_offset
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 thereattributed
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
- 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
- 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 validos_name
values:
android bada blackberry ios linux macos server symbian unknown webos windows windows-phone
Device Types
A list of validdevice_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 thehuman_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
orgrouping=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.
trackers
: will group by network / campaign / adgroup / creative depending on the optionally giventracker_token
. See the Trackers Tree section for more on tracker grouping.networks
: will group by network independent of the optionally giventracker_token
. The result set will include a networks field holding an array of found networks.campaigns
: will group by network independent of the optionally giventracker_token
. The result set will include a campaigns field holding an array of found campaigns.adgroups
: will group by network independent of the optionally giventracker_token
. The result set will include an adgroups field holding an array of found adgroups.creatives
: will group by network independent of the optionally giventracker_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 adates
field holding an array of applicable hours of the period, where the correspondingdate
field lists the hour.day
: will group by day. The result set will include adates
field holding an array of applicable days of the period, where the correspondingdate
field lists the dayweek
: will group by week. The result set will include adates
field holding an array of applicable weeks, where the correspondingdate
field lists the start date of the week.month
: will group by month. The result set will include adates
field holding an array of applicable months, where the correspondingdate
field lists the first of the month.
Further Grouping Options
countries
: will group by country. The result set will include acountries
field holding an array of found countries, where the correspondingcountry
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 aregion
field holding an array of found regions, where the correspondingregion
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 adevice_types
field holding an array of found device_types, where the correspondingdevice_type
field names the type of device out of the list in thedevice_types
section above.os_names
: will group by OS name. The result set will include anos_names
field holding an array of found os_names, where the correspondingos_names
field names the operating system of the devices.partners
: will group by partner name. The result set will include apartners
field holding an array of found partners, where the correspondingpartner
field names the partner to which the data belongs.
Trackers Tree
As mentioned, all endpoints could be requested either with or without specifying a tracker token. For each resource above, two endpoints are specified, where the second form specifies a tracker. If you use the second form, the result set will be filtered by the tracker that you provide, and the trackers
grouping would segment your result set by subtracker.If no tracker token is given, data for every network is returned, and the
trackers
grouping would segment your result set by network-level trackers as an entry in the trackers
array.With the
trackers
grouping, the result set will contain metadata for each tracker. This metadata includes a has_subtrackers
boolean field, which indicates that you could also query the given token to traverse the tree deeper.For example, if you request a query with a Campaign parent tracker, the response will contain the data grouped by the respective Adgroup subtrackers.
Tracker Filtering
Tracker filtering is useful for handling complicated tracker setups. You can focus your result set to data from specific trackers by using the tracker_filter
query parameter with any of your KPI Service queries. This combined with the Grouping options provided by the API create a powerful facility for drilling down into your data while retaining focus on given Networks, Campaigns or Adgroups.Say
x2yiy3
and vi4wwc
are two Network tracker-tokens in your Adjust tracker setup. You are able to refine the result set to only contain data belonging to or descending from these two Networks by using the query parameters:&tracker_filter=x2yiy3,vi4wwc&grouping=network,campaign,adgroup,creative
Note that the
grouping
parameter is optional. In fact any grouping
(or none at all) could give you meaningful results depending on your research goals.Furthermore, the tracker filtering could be used in combination with the Multiple-Apps-Overview Endpoint, like so:
GET https://api.adjust.com/kpis/v1?app_tokens=44cdcdck2syc,9xmtsnp687ek&tracker_filter=q9y2y2,xi2wxq,x2yiy3,vi4wwc&grouping=app,network,campaign,adgroup,creative
This way you can, for example, compare the performances of the same networks for multiple apps in a single API call.
Multiple-Apps-Overview Endpoint
The endpoints discussed thus far request data for only a single app. These are essential for a full breakdown of an individual app, but will not give you an overview for multiple (or even all) of the apps you track on Adjust. A full overview is made possible with the multiple-apps endpoint, which we discuss here.Endpoint URL
There are two different endpoints for deliverables that you can call:GET https://api.adjust.com/kpis/v1{.csv|.json}?app_tokens=44cdcdck2syc,9xmtsnp687ek GET https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek{.csv|.json}?
Both endpoints will return the same results.
Regarding cohorts, you would need to use the following endpoint:
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek/cohorts{.csv|.json}?
Note that, same as with all other endpoints, the
.csv
or .json
extensions are not mandatory here. The default response format is again JSON, but if you need to change it to CSV you are only required to append the .csv
extension.Param Name | Format | Description |
---|---|---|
start_date | YYYY-MM-DD | The start date of the selected period. |
end_date | YYYY-MM-DD | The end date of the selected period. |
utc_offset | [+-]HH:MM, e.g. utc_offset=-05:00 or utc_offset=10:00 | UTC offset for timezones |
kpis | string, e.g. clicks,installs,maus | Comma-separated list of App KPIs. Any combination of App KPIs is accepted. |
sandbox | string true or false | Requests could be issued for Sandbox or Production data. By default, Production is assumed. |
impression_based | string true or false | Requests could be issued as click or impression based view. By default, click based is assumed. |
countries | string, e.g. de,us | Comma-separated list of ISO 3166 alpha-2 country names. |
os_names | string, e.g. ios,android | Comma-separated list of OS names. The list of OS names applies. |
device_types | string, e.g. phone,tablet | Comma-separated list of device types. The list of Device Types applies. |
grouping | string, e.g. apps,countries | Grouping parameters. See below for more details on grouping. |
human_readable_kpis | boolean | Print the headlines in English formatting (e.g. following appropriate capitalization rules). |
App KPIs
It’s worth repeating that for thekpis
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 theapps
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 |