Documentation

Advertising Statistics API

Advertising Statistics API

Advertising Statistics API

Overview

Note: The following documentation applies to the current API version; aspects of the domain and functionality are subject to change for general release.
The Statistics API is an HTTP interface that allows advertisers to retrieve acquisition statistics data in CSV format.

Contact

If you have any questions or feedback regarding the API you can reach out to us at unityads-support@unity3d.com.

Migrating from the previous version of the API

This version (V2) of the API introduces several key updates:
  • It has a new URL for access, and it incorporates the use of the core organization ID.
  • An overhauled authentication method.
  • Changes in the query parameters may affect how data is retrieved and processed.

New URL and organization ID

https://services.api.unity.com/advertise/stats/v2/organizations/:organization_id/reports/acquisitions
Where 
organization_id
identifies your organization.
To look up the organization ID, please use the following steps:
  1. Open the Unity Ads User Acquisition dashboard.
  2. Select Settings from the navigation.
  3. On the settings page, you will see two separate Organization ID fields. Pick the value from the Organization core ID field.

Authentication

A service account is required to access the API. Please see the related authentication section.

Query parameters

V1

V2

start
start
end
end
scale
scale
(Reduced options: 
year
and 
quarter
are not supported)
fields
metrics
(Reduced options: No dimensions like 
country
and no SKAN)
splitBy
breakdowns
(Breakdown data is automatically added to the response without the need to specify them, and timestamp is always included)
targets
gameIds
campaignSets
appIds
campaigns
campaignIds
creativePacks
creativePackIds
adTypes
creativePackTypes
countries
countries
platforms
platforms
stores
Not supported
osVersions
Not supported
sourceAppIds
Not supported
skadConversionValues
Not supported

SKAdNetwork (SKAN) data

SKAN data is available in its own endpoint. Refer to the endpoint documentation section later for detailed information on this endpoint.

Authentication

Using the Unity Advertising Statistics API requires a service account. You can find information on how to create a service account here.
Once you've created a service account, you must assign the Advertise Stats API Viewer role to it, which you will find under the 'Growth' category. Note that if your MMP asks you to create a service account for them, you must give a service account with the Advertise Stats API MMP Viewer role instead.
Note: You can also assign the Advertise Stats API Viewer to your existing service accounts.
You can use the service account to authenticate with the API:
  1. In your service account detail page, click the Create key button. There will be a modal that consists Key ID and Secret key. Remember to save the secret key as it will not be shown again.
  2. Place the Key ID and Secret key in the 
    Authorization
    header of the GET request, prefixed with 
    Basic
    . For example:
curl -H "Authorization: Basic <key id>:<secret key>" https://services.api.unity.com/advertise/stats/v2/organizations/:organization_id/reports/acquisitions

Rate Limits

The API enforces a rate limit based on two criteria: organization ID and IP address.
The rate limit is 1 request per second and 30 requests per 30 minutes, applied to each organization ID and each IP address separately. The limit is reached when either the request rate for an organization ID or the request rate for an IP address reaches these thresholds, whichever occurs first.
The API responds with 
429
HTTP status code if the rate limit is exceeded.

Handling Large Data Queries

Excessive data breakdown, especially using the 
sourceAppId
dimension, can significantly increase response size and complexity. Please note that the maximum allowed request duration is 10 minutes. Requests exceeding this limit may result in an incomplete response, potentially leading to data loss.
We recommend querying data one day at a time to prevent large-sized responses or timeouts when breaking down data by 
sourceAppId
, 
country
, or other dimensions with numerous unique values. This approach ensures manageable data sizes and reliable retrieval.

Data

The API will show up to 2 years of data, starting from May 21, 2024. Hourly data will be available for the most recent six months, while older data will be aggregated daily. The data is updated once an hour at an unspecified time.
The data provided is historical. For instance, if the campaign name was altered during the specified time period, the name presented will correspond to what it was on that particular day.
The pre-install metrics are updated with a delay of 85 minutes, and they are reported in Universal Time Coordinated (UTC). To illustrate, the complete updates for the pre-install metrics from 11-12 are available at 13:25 UTC.

Report Format

Data is available in CSV (default) or JSON format. To retrieve JSON, append 
format=json
to the URL.

Response Compression

The API supports response compression. Responses are compressed when the request includes the 
Accept-Encoding: gzip
or 
Accept-Encoding: deflate
header.

Response Status and Error Codes

This API follows the Unity Services Web Response status and error codes.
If a response is empty and no data exists for the requested filters, the response will lead to an HTTP response status code 204 (no content).

API Lifecycle

This API follows the Unity Services Web API Lifecycle.

Change log

  • June 23, 2026:
    • New post-install metrics added: 
      d[x]Payer
      , 
      d[x]PayerRate
      , 
      d[x]CostPerPayer
  • May 21, 2026:
    • Added new "unity app id" field to the response when using the 
      breakdowns
      parameter with the 
      app
      value.
    • "appIds" filter option now supports both legacy app id and unity app id.
  • Jan 30, 2026:
    • Added 
      eofMarker
      query parameter for CSV responses. When enabled, appends an end-of-file marker row to indicate complete downloads, allowing clients to detect partial or truncated CSV data.
  • June 10, 2025:
    • Added d21 and d28 window support for 
      d[x]AdRevenue
      , 
      d[x]AdRevenueRoas
      , 
      d[x]IapRevenue
      , 
      d[x]IapRoas
      , 
      d[x]Purchases
      , 
      d[x]UniquePurchasers
      , 
      d[x]Retained
      , 
      d[x]RetentionRate
      , 
      d[x]TotalRoas
      , 
      d[x]LevelComplete
      , 
      d[x]CostPerLevelComplete
      , 
      d[x]LevelCompleteRate
      metrics.
  • February 20, 2025: Response Compression Support.
  • February 19, 2025: Added support for JSON format.
  • February 14, 2025:
    • Data is available up to 2 years, starting from May 21, 2024.
    • Hourly data is available for the most recent six months, while older data is aggregated daily.
  • August 19, 2024:
    • New metrics added to the list 
      • d[x]LevelComplete
        , 
        d[x]CostPerLevelComplete
        , 
        d[x]LevelCompleteRate
    • New breakdown options added: 
      eventType
      , 
      eventName
    • New filter options added: 
      eventTypes
      , 
      eventNames
  • August 05, 2024:
    • More post-install days support added.
      • Supported days now include: 0, 1, 3, 7, and 14.
      • Added more post-install days support for the following metrics: 
        d[x]AdRevenueRoas
        , 
        d[x]IapRoas
        , and 
        d[x]TotalRoas
        .
    • New metrics added to the list. 
      • d[x]AdRevenue
        , 
        d[x]IapRevenue
        , 
        d[x]Purchases
        , 
        d[x]UniquePurchasers
        , 
        d[x]Retained
        , 
        d[x]RetentionRate
  • May 16, 2024: "Handling Large Data Queries" section added.
  • January 24, 2024: SKAN endpoint added.
  • January 18, 2024: Added data freshness note to documentation.
  • November 21, 2023: Unity Advertiser Statistics API version 2 released.

Glossary

Metrics

Basic

Metric

Description

Note

startsThe number of times a user starts your ad.Starts are also known as impressions.
viewsThe number of times users watched your entire ad.
clicksThe number of times a user clicks the call-to-action button in your ad.
installsThe number of users who install your app after watching the ad.
spendThe advertising budget spent.Spend is calculated by multiplying the number of installs by the cost per install (CPI).
cpiCost per install (CPI): the average cost to the advertiser per install.CPI is calculated by dividing the Spend amount by the number of installs.
ctrClick through rate (CTR): the percentage of users who clicked the call-to-action button after watching your ad.CTR is calculated by dividing the number of clicks by the number of starts.
cvrConversion rate (CVR): the percent of users who installed your app after watching the ad.CVR is calculated by dividing the number of installs by the number of starts.
ecpmThe estimated cost in dollars per 1,000 starts (effective cost per mille).

Post-install

Post-install metrics are provided for specific timeframe after a user installs the app and are represented using the "Dx" format, where:
  • "d" stands for "day".
  • "x" is a placeholder for the number of days after install.
Example: "d7AdRevenue" represents the ad revenue generated within the 7-day timeframe.

Metric

Description

Supported Days

Note

d[x]AdRevenueRevenue from your ad campaign.0, 1, 3, 7, 14, 21, 28
d[x]AdRevenueRoasAd revenue return on ad spend.0, 1, 3, 7, 14, 21, 28Ad revenue roas is calculated by dividing the revenue earned by the amount spent on advertising.
d[x]IapRevenueRevenue from users purchasing in-app items.0, 1, 3, 7, 14, 21, 28
d[x]IapRoasIn-app purchase revenue return on ad spend.0, 1, 3, 7, 14, 21, 28IAP roas is calculated by dividing the IAP revenue earned by the amount spent on advertising.
d[x]PurchasesIn-app transactions made in your app.0, 1, 3, 7, 14, 21, 28
d[x]UniquePurchasersThe number of first-time in-app purchasers within the selected time interval.0, 1, 3, 7, 14, 21, 28
d[x]RetainedThe number of users continuing to engage with your app for the selected time period.0, 1, 3, 7, 14, 21, 28
d[x]RetentionRateThe percentage of users who continue engaging with an app over time.0, 1, 3, 7, 14, 21, 28Retention rate is calculated by dividing the number of retained users by the number of installs.
d[x]TotalRoasThe total return on ad spend (ROAS) within the selected dx timeframe.0, 1, 3, 7, 14, 21, 28Total roas is calculated by adding IAP revenue and ad revenue, then dividing by your spend.
d[x]LevelCompleteThe number of users who completed a specified level.0, 1, 3, 7, 14, 21, 28
d[x]CostPerLevelCompleteThe average cost for a user who completed a specified level.0, 1, 3, 7, 14, 21, 28
d[x]LevelCompleteRateThe percentage of users who completed a specified level per install.0, 1, 3, 7, 14, 21, 28
d[x]PayerThe number of users who made a payment.0, 1, 3, 7, 14, 21, 28
d[x]PayerRateThe percentage of payers per install.0, 1, 3, 7, 14, 21, 28
d[x]CostPerPayerThe average cost for a user who made a payment.0, 1, 3, 7, 14, 21, 28
Download OpenAPI specification:

Acquisitions Report

This endpoint returns Acquisitions reports in CSV format that are under the given organization.
Authorizations
ServiceAccount (advertise.stats.get)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: advertise.stats.get

Path parameters for "Acquisitions Report"

organizationId

string
required
example: 5772916123937
Unique identifier for an Organization.
Please use the following steps to look up the organization ID:
  1. Open the Acquire Dashboard
  2. Select Settings from the navigation
  3. On the settings page, you will see two separate Organization IDs. For the Advertising statistics API, pick the value that is labeled as 
    Organization core ID
    .

Header parameters for "Acquisitions Report"

Accept-Encoding

string
No description

Query parameters for "Acquisitions Report"

start

string
required
example: 2023-10-01T13:00:00.000Z
Start time of the data query in 
ISO 8601
format. It must be within the data retention limits. The API includes data starting at this timestamp.

end

string
required
example: 2023-10-01T14:00:00.000Z
End time of the data query in 
ISO 8601
format. The API includes data up to but not including the end time.

scale

string
required
example: hour
Time resolution of the data.

metrics

string
required
You can specify comma-separated fields to display in your report.
Options
  • starts
  • views
  • clicks
  • installs
  • spend
  • cpi
  • ctr
  • cvr
  • ecpm
  • d0AdRevenue
  • d1AdRevenue
  • d3AdRevenue
  • d7AdRevenue
  • d14AdRevenue
  • d21AdRevenue
  • d28AdRevenue
  • d0AdRevenueRoas
  • d1AdRevenueRoas
  • d3AdRevenueRoas
  • d7AdRevenueRoas
  • d14AdRevenueRoas
  • d21AdRevenueRoas
  • d28AdRevenueRoas
  • d0IapRevenue
  • d1IapRevenue
  • d3IapRevenue
  • d7IapRevenue
  • d14IapRevenue
  • d21IapRevenue
  • d28IapRevenue
  • d0IapRoas
  • d1IapRoas
  • d3IapRoas
  • d7IapRoas
  • d14IapRoas
  • d21IapRoas
  • d28IapRoas
  • d0Purchases
  • d1Purchases
  • d3Purchases
  • d7Purchases
  • d14Purchases
  • d21Purchases
  • d28Purchases
  • d0UniquePurchasers
  • d1UniquePurchasers
  • d3UniquePurchasers
  • d7UniquePurchasers
  • d14UniquePurchasers
  • d21UniquePurchasers
  • d28UniquePurchasers
  • d0Retained
  • d1Retained
  • d3Retained
  • d7Retained
  • d14Retained
  • d21Retained
  • d28Retained
  • d0RetentionRate
  • d1RetentionRate
  • d3RetentionRate
  • d7RetentionRate
  • d14RetentionRate
  • d21RetentionRate
  • d28RetentionRate
  • d0TotalRoas
  • d1TotalRoas
  • d3TotalRoas
  • d7TotalRoas
  • d14TotalRoas
  • d21TotalRoas
  • d28TotalRoas
  • d0LevelComplete
  • d1LevelComplete
  • d3LevelComplete
  • d7LevelComplete
  • d14LevelComplete
  • d21LevelComplete
  • d28LevelComplete
  • d0CostPerLevelComplete
  • d1CostPerLevelComplete
  • d3CostPerLevelComplete
  • d7CostPerLevelComplete
  • d14CostPerLevelComplete
  • d21CostPerLevelComplete
  • d28CostPerLevelComplete
  • d0LevelCompleteRate
  • d1LevelCompleteRate
  • d3LevelCompleteRate
  • d7LevelCompleteRate
  • d14LevelCompleteRate
  • d21LevelCompleteRate
  • d28LevelCompleteRate
  • d0Payer
  • d1Payer
  • d3Payer
  • d7Payer
  • d14Payer
  • d21Payer
  • d28Payer
  • d0PayerRate
  • d1PayerRate
  • d3PayerRate
  • d7PayerRate
  • d14PayerRate
  • d21PayerRate
  • d28PayerRate
  • d0CostPerPayer
  • d1CostPerPayer
  • d3CostPerPayer
  • d7CostPerPayer
  • d14CostPerPayer
  • d21CostPerPayer
  • d28CostPerPayer

breakdowns

string
You can specify a comma-separated list of dimensions by which to split data. Each breakdown should be a valid keyword, such as app, campaign, platform, etc. Do not include spaces after the commas. While metrics give you the overall numbers, breakdowns allow you to see those numbers by different segments. In practice, using a metric like "installs" combined with a breakdown by "country" would detail how many installs came from each specific country.
Options
  • app
  • campaign
  • country
  • creativePack
  • creativePackType
  • osVersion
  • platform
  • sourceAppId
  • store
  • targetGame
  • eventType
  • eventName

Split data

Split 
app
data results in three fields:
  • app id
  • app name
  • unity app id (this id can be empty for customers who have not been migrated to the new Unity Dashboard experience. Migrations are happening in May - July 2026)
Split 
campaign
data results in two fields:
  • campaign id
  • campaign name
Split 
creativePack
data results in two fields:
  • creative pack id
  • creative pack name
Split 
targetGame
data results in three fields:
  • target id
  • target store id
  • target name
Note: Splitting data by too many dimensions may impact response times for querying the API. We recommend querying data one day at a time to prevent large-sized responses or timeouts when breaking down data by 
sourceAppId
, 
country
, or other dimensions with numerous unique values.

appIds

string
A comma-separated list of app IDs to filter. Each ID matches rows where either the legacy app id or the unity app id column equals that value.

campaignIds

string
A comma-separated list of campaign IDs to filter.

gameIds

string
A comma-separated list of target game IDs to filter.

creativePackIds

string
A comma-separated list of creative pack IDs to filter.

creativePackTypes

string
A comma-separated list of creative pack types to filter.
Options
  • video
  • playable
  • video+playable

countries

string
A comma-separated list of country codes to filter.
Country code in 
ISO 3166-1 alpha-2
format.

platforms

string
A comma-separated list of platforms to filter.

eventTypes

string
A comma-separated list of event types to filter. This is type of event you set up with your MMP. This could be an "in-app purchase" type of event, or a "complete level" type of event

eventNames

string
A comma-separated list of event names to filter. This is the specific event you set up with your MMP. It is a specific in-app purchase event (for example, buy_10_diamonds or 10_USD_store_purchase) or a specific complete level event (for example, finish_lvl_20)

format

string
The response format. The default is CSV.

eofMarker

boolean
When set to 
true
, appends an end-of-file marker row to CSV responses to indicate that the download is complete. This allows clients to distinguish between complete and partial (truncated) CSV downloads.
The marker row has the format 
#__EOF__,rows=N
followed by empty columns to match the CSV column count. If the EOF marker is present, the download is complete. If it's missing, the download may be partial or incomplete.
The marker row is only added when:
  • The response format is CSV (not JSON)
  • The response contains data (not empty)
Example: For a CSV with 5 columns and 10 data rows, the EOF marker row would be: 
#__EOF__,rows=10,,,
Use case: When downloading large CSV files, clients can verify download completeness by checking for the EOF marker at the end of the response.

HTTP response status codes for "Acquisitions Report":

Code samples for "Acquisitions Report":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/stats/v2/organizations/{organizationId}/reports/acquisitions"

Response example

{ "data": [ { "timestamp": "2020-10-01", "campaignId": "50ed569d57fe1f324a15fbf7", "campaignName": "Campaign #5", "country": "AU", "clicks": 71, "installs": 30, "spend": 45 }, { "timestamp": "2020-10-01", "campaignId": "50eeb7339e10c9d21c0225cb", "campaignName": "Campaign #6", "country": "AT", "clicks": 39, "installs": 19, "spend": 28.5 } ]}

SKAN Report

This endpoint returns SKAN reports in CSV format under the given organization.
Authorizations
ServiceAccount (advertise.stats.get)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: advertise.stats.get

Path parameters for "SKAN Report"

organizationId

string
required
example: 5772916123937
Unique identifier for an Organization.
Please use the following steps to look up the organization ID:
  1. Open the Acquire Dashboard
  2. Select Settings from the navigation
  3. On the settings page, you will see two separate Organization IDs. For the Advertising statistics API, pick the value that is labeled as 
    Organization core ID
    .

Header parameters for "SKAN Report"

Accept-Encoding

string
No description

Query parameters for "SKAN Report"

start

string
required
example: 2023-10-01T13:00:00.000Z
Start time of the data query in 
ISO 8601
format. It must be within the data retention limits. The API includes data starting at this timestamp.

end

string
required
example: 2023-10-01T14:00:00.000Z
End time of the data query in 
ISO 8601
format. The API includes data up to but not including the end time.

scale

string
required
example: hour
Time resolution of the data.

metrics

string
required
you can specify comma-separated fields to display in your report.
Options
  • starts
  • views
  • clicks
  • installs
  • spend
  • cpi
  • cvr
The pre-install data (e.g., clicks) is from devices that support SKAdNetwork. Installs are derived from SKAdNetwork and include re-downloads.

breakdowns

string
You can specify a comma-separated list of dimensions by which to split data. Each breakdown should be a valid keyword, such as app, campaign, etc. Do not include spaces after the commas. While metrics give you the overall numbers, breakdowns allow you to see those numbers by different segments. In practice, a metric like "installs" combined with a breakdown by "app" would detail how many installs came from each specific app.
Options
  • app
  • campaign
  • conversionValue
  • targetGame
The conversion value is the fine-grained conversion value. Please note that breakdown with conversion value does not work with pre-install data (e.g., clicks).

Split data

Split 
app
data results in three fields:
  • app id
  • app name
  • unity app id (this id can be empty for customers who have not been migrated to the new Unity Dashboard experience. Migrations are happening in May - July 2026)
Split 
campaign
data results in two fields:
  • campaign id
  • campaign name
Split 
conversionValue
data being split by the conversion value
Split 
targetGame
data results in three fields:
  • target id
  • target store id
  • target name
Note: Splitting data by too many dimensions may impact response times for querying the API.

appIds

string
A comma-separated list of app IDs to filter. Each ID matches rows where either the legacy app id or the unity app id column equals that value.

campaignIds

string
A comma-separated list of campaign IDs to filter.

gameIds

string
A comma-separated list of target game IDs to filter.

format

string
The response format. The default is CSV.

eofMarker

boolean
When set to 
true
, appends an end-of-file marker row to CSV responses to indicate that the download is complete. This allows clients to distinguish between complete and partial (truncated) CSV downloads.
The marker row has the format 
#__EOF__,rows=N
followed by empty columns to match the CSV column count. If the EOF marker is present, the download is complete. If it's missing, the download may be partial or incomplete.
The marker row is only added when:
  • The response format is CSV (not JSON)
  • The response contains data (not empty)
Example: For a CSV with 5 columns and 10 data rows, the EOF marker row would be: 
#__EOF__,rows=10,,,
Use case: When downloading large CSV files, clients can verify download completeness by checking for the EOF marker at the end of the response.

HTTP response status codes for "SKAN Report":

Code samples for "SKAN Report":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/stats/v2/organizations/{organizationId}/reports/skan"

Response example

{ "data": [ { "timestamp": "2024-01-15", "appId": "30ed569d57fe1f324a15fbe7", "appName": "App #1", "unityAppId": "7f2c8a91-4d3b-4e1f-9a2c-6b5d4e3f2a10", "starts": 2894, "installs": 40, "spend": 62.5 }, { "timestamp": "2024-01-15", "appId": "30ed569d57fe1f324a15fbe8", "appName": "App #2", "unityAppId": "3b9e1c7f-8a2d-4f6e-b4c1-0d9e8f7a6b5c", "starts": 1258, "installs": 16, "spend": 23.95 } ]}