SKAN aggregated performance report API

For:
Marketers
Last update:

At a glance: SKAN performance enriched with additional data points. Similar to the data in the SKAdNetwork dashboard. Aggregate using either the install date or postback arrival date.

SKAN aggregated performance report API

API basics

Overview

The API returns attribution metrics reported by Apple SKAdNetwork (real data) and other data points using the install or postback arrival date. The report is similar in structure to the data presented in the SKAN dashboard. 
Data freshness

Data availability is according to the SKAN data freshness rate.
Path API V1 token

https://hq1.appsflyer.com/api/skadnetworks/v1/data/app/<app_id>

V1 is deprecated. The sunset date will be announced in the future. 
Path API V2 token

https://hq1.appsflyer.com/api/skadnetworks/v2/data/app/<app_id>
Path API V2 token for SKAN 4 https://hq1.appsflyer.com/api/skadnetworks/v3/data/app/<app_id>
Path parameters (mandatory)

<app_id>: Is the app identifier as found in the AppsFlyer dashboard. Insert it exactly as it displays in the dashboard. Example: id123456789

Query parameters

 Listed in the table that follows.
HTTP method GET
Response content type text/plain
Authorization

Authorization HTTP header containing API V2.0 token (Bearer token) is required.

AppsFlyerAdmin_us-en.pngAn admin user gets the V2 token in the dashboard, go to your email address > API tokens. 
Date limitations
  • When setting the date range the most recent date should be the current date UTC time zone minus 3 days. Meaning on March 31, use March 28. 
  • Earliest date supported: November 1, 2020
  • Maximum query range: 90 days
Rate limitation
  • Queries return up to 50K rows
  • 10 calls per minute
SRN-related remarks
  • Meta ads: data is available. 
  • Google Ads: Installs can be recorded up to 13 days post-install due to the Google click-time methodology. If you query Google data for the last 13 days every day, this provides the coverage needed for Google SKAN data.

Query parameters

Parameter name Format Mandatory

date_type

The date type used in the date range bounded by start_date and end_date

Options: 

  • [Default] install: The install date derived by AppsFlyer using the postback arrival time and after considering the measurement period.
  • arrival: The postback arrival time. Note: Organic install metrics have the value N/A. 

Google Ads data: The install and arrival dates are the same due to the Google Ads reporting methodology. 

 No

start_date

 

The install date range is bounded by start_date and end_date. Note! Install date differs from postback arrival date. 

  • Earliest install date having format YYYY-MM-DD 
  • Earliest date permitted: 2020-11-01
    Example: 2020-11-05
Yes
end_date
  • Most recent install date having format YYYY-MM-DD
  • Maximum number of days per report call: 90 days 
  • Example: 2020-11-12
Yes
view_type

Filter the installs by type as follows: 

  • acquisition: Installs 
  • retargeting: Redownloads
  • unified: Acquisition and redownloads combined.
  • [Default] unified
  • Cost, click, and impression metrics return when view_type=unified

No
modeled_conversion_values
  • Only available from V2
  • Value can be either true or false
  • If true, the postback includes the modeled data when populating the decoded metric columns. See available fields
  • If false, the postback presents decoded data as received by raw SKAN postbacks, without modeled data.
  • Default value is false.

No

Request example (cURL)

curl --request \
GET 'https://hq1.appsflyer.com/api/skadnetworks/v3/data/app/<app_id>?start_date=2020-11-10&end_date=2020-11-20' \
--header 'Authorization: Bearer <V2_AUTH_TOKEN_HERE (700+ characters string)>'

Report structure and example

The API returns a CSV file with the following naming scheme:

<app_id>_skadnetworks_report_<view_type>
_<start-date>_<end-date>_<unique-report_hash>_UTC_.csv

Available fields

  • Columns and metrics available are listed in the table that follows. 
  • Some metrics (revenue, engagement, conversion) depend on the SKAN performance measurement settings.
  • The report includes only the in-app events that users performed during the reporting period. As such, the number and sequence of in-app event columns can change from report to report. Don't rely on column sequence in designing your data import process.
  • Examples: V1 | V2

SKAdNetwork aggregate report structure

Column name Dimension or metric Available with API V1 token  Available with API V2 token

Available with API V2 token (for SKAN 4)

 Available with modeled data only filter

Date 

The data is according to the selected date_type.

 Group by  N Y Y Y
Media Source (pid) Group by Y Y Y Y
Campaign (c)

Group by

Y

Y

Y

Y
Campaign ID Group by Y Y Y Y
Site ID Group by Y Y Y N
Adset Group by N Y Y Y
Adset ID Group by N Y Y Y
Ad Group by N Y Y N
Ad ID Group by N Y Y N
Country Group by Y  Y Y N

AF Attribution Flag

See: SSOT guide

 Group by N Y Y Y

Postback sequence index

 Group by N N Y Y

Creative

 Group by N N Y N

Channel

 Group by N N Y N
Impressions Metric Y Y Y Y
Clicks Metric Y Y Y Y
CTR Metric Y Y Y Y
Installs Metric Y Y Y Y

Click Through Installs (fidelity_type = 1)

 Metric Y Y Y Y

View Through Installs

(fidelity_type = 0)

 Metric Y Y Y Y

Null Conversion Value Rate

[Available starting Jan 23, 2022] 

 Metric N Y Y Y
Conversion Rate Metric Y Y Y Y
Converted Users Metric Y Y Y Y
Converted Users/Installs Metric Y Y Y Y
Total Revenue Revenue metric Y Y Y Y
Total Cost Metric Y Y Y Y
ROI Revenue metric Y Y Y Y
ARPU Revenue metric Y Y Y Y
Average eCPI Metric Y Y Y Y
{af_skad_revenue} (Unique users) Revenue metric Y Y Y Y
{af_skad_revenue} (Event counter) Revenue metric Y Y Y Y

{your in-app event name} (Unique users) 

 Metric Y Y Y Y
{your in-app event name} (Event counter)  Metric Y Y Y Y

Traits 

Trait Remarks 
Ad network access  If you are an analytics partner, ask the advertiser to grant you permission.
Agency access Not available
App-specific time zone UTC only
App-specific currency  Always USD
Organic data Calculated as the difference between all data reported by SDK directly to AppsFlyer less non-organic data reported by SKAN postbacks
Non-organic data Calculated using SKAN postbacks received by AppsFlyer
Historical data Earliest conversion data (install or retarget) supported: November 1, 2020
Account user access The authorization token is available to an admin user in the dashboard.
Total cost SKAN API may not include the total cost metric if the regular attribution (regular Overview) contains SKAN campaigns that in the lowest granularity level (for example: ad, country, or site ID) have more than 50K rows.

HTTP response codes and troubleshooting

HTTP Response

Remarks
200 OK

Valid data returned (CSV)
200 OK

Empty report - no data found for the specified date range (CSV, only column names are returned).

  • In the SKAdNetwork dashboard, verify that data is available for the specified date range.
  • Verify that start_date is a date earlier than yesterday. The earliest recommended date is the current date UTC time, less 3 days. For example: If the current date UTC timezone is March 31, the earliest date you should use is March 28. 
400 Bad request

Missing or invalid query parameters
401 Unauthorized

Authorization token is missing or invalid

Make sure you use the token correctly
401 Too many requests

Exceeded rate limitation
403 No permission You don't have permission to access this report. If you are an analytics partner ask the advertiser to give you permission. 
404 Not found