````json { "openapi": "3.0.0", "x-publicDocumentationRedocOptions": [ "no-auto-auth", "max-displayed-enum-values=\"10\"" ], "tags": [ { "name": "Acquisitions", "description": "Retrieve acquisition statistics." }, { "name": "SKAN", "description": "Retrieve SKAdNetwork statistics." } ], "info": { "title": "Advertising Statistics API", "version": "v2.0 latest", "contact": { "name": "Unity Ads Support", "email": "unityads-support@unity3d.com" }, "description": "# Overview\n**Note**: The following documentation applies to the current API version; aspects of the domain and functionality are subject to change for general release.\n\nThe Statistics API is an HTTP interface that allows advertisers to retrieve acquisition statistics data in CSV format.\n\n## Contact\nIf you have any questions or feedback regarding the API you can reach out to us at unityads-support@unity3d.com.\n\n# Migrating from the previous version of the API\n\nThis version (V2) of the API introduces several key updates: \n- It has a new URL for access, and it incorporates the use of the core organization ID.\n- An overhauled authentication method.\n- Changes in the query parameters may affect how data is retrieved and processed.\n\n## New URL and organization ID\n`https://services.api.unity.com/advertise/stats/v2/organizations/:organization_id/reports/acquisitions`\n\nWhere `organization_id` identifies your organization.\n\nTo look up the organization ID, please use the following steps:\n1. Open the Unity Ads User Acquisition [dashboard](https://cloud.unity.com/acquire).\n2. Select Settings from the navigation.\n3. On the settings page, you will see two separate Organization ID fields. Pick the value from the *Organization core ID* field.\n\n## Authentication\nA service account is required to access the API. Please see the related authentication section.\n\n## Query parameters\n| V1 | V2 |\n|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------|\n| `start` | `start` |\n| `end` | `end` |\n| `scale` | `scale` (Reduced options: `year` and `quarter` are not supported) |\n| `fields` | `metrics` (Reduced options: No dimensions like `country` and no SKAN) |\n| `splitBy` | `breakdowns` (Breakdown data is automatically added to the response without the need to specify them, and timestamp is always included)|\n| `targets` | `gameIds` |\n| `campaignSets` | `appIds` |\n| `campaigns` | `campaignIds` |\n| `creativePacks` | `creativePackIds` |\n| `adTypes` | `creativePackTypes` |\n| `countries` | `countries` |\n| `platforms` | `platforms` |\n| `stores` | Not supported |\n| `osVersions` | Not supported |\n| `sourceAppIds` | Not supported |\n| `skadConversionValues` | Not supported |\n\n## SKAdNetwork (SKAN) data\n\nSKAN data is available in its own endpoint.\nRefer to the endpoint documentation section later for detailed information on this endpoint.\n\n# Authentication\nUsing the Unity Advertising Statistics API requires a service account.\nYou can find information on how to create a service account here.\n\nOnce 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.\nNote 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.\n\n**Note**: You can also assign the Advertise Stats API Viewer to your existing service accounts.\n\nYou can use the service account to authenticate with the API:\n1. 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.\n\n2. Place the Key ID and Secret key in the `Authorization` header of the GET request, prefixed with `Basic`. For example:\n```\ncurl -H \"Authorization: Basic :\" https://services.api.unity.com/advertise/stats/v2/organizations/:organization_id/reports/acquisitions\n```\n\n# Rate Limits\nThe API enforces a rate limit based on two criteria: organization ID and IP address.\n\nThe rate limit is 1 request per second and 30 requests per 30 minutes, applied to each organization ID and each IP address separately.\nThe 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.\n\nThe API responds with `429` HTTP status code if the rate limit is exceeded.\n\n# Handling Large Data Queries\n\nExcessive data breakdown, especially using the `sourceAppId` dimension, can significantly increase response size and complexity.\nPlease note that the maximum allowed request duration is 10 minutes.\nRequests exceeding this limit may result in an incomplete response, potentially leading to data loss.\n\nWe 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.\nThis approach ensures manageable data sizes and reliable retrieval.\n\n# Data\nThe 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.\n\nThe 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.\n\nThe 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.\n\n# Report Format\nData is available in CSV (default) or JSON format. To retrieve JSON, append `format=json` to the URL.\n\n# Response Compression\nThe API supports response compression.\nResponses are compressed when the request includes the `Accept-Encoding: gzip` or `Accept-Encoding: deflate` header.\n\n# Response Status and Error Codes\nThis API follows the Unity Services Web Response status and error codes.\n\nIf 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).\n\n# API Lifecycle\nThis API follows the Unity Services Web API Lifecycle.\n\n# Change log\n- June 23, 2026:\n - New post-install metrics added: `d[x]Payer`, `d[x]PayerRate`, `d[x]CostPerPayer`\n- May 21, 2026:\n - Added new \"unity app id\" field to the response when using the `breakdowns` parameter with the `app` value.\n - \"appIds\" filter option now supports both legacy app id and unity app id.\n- Jan 30, 2026:\n - 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.\n- June 10, 2025:\n - Added d21 and d28 window support for `d[x]AdRevenue`, `d[x]AdRevenueRoas`, `d[x]IapRevenue`, `d[x]IapRoas`, `d[x]Purchases`, \n `d[x]UniquePurchasers`, `d[x]Retained`, `d[x]RetentionRate`, `d[x]TotalRoas`, `d[x]LevelComplete`, \n `d[x]CostPerLevelComplete`, `d[x]LevelCompleteRate` metrics.\n- February 20, 2025: Response Compression Support.\n- February 19, 2025: Added support for JSON format.\n- February 14, 2025:\n - Data is available up to 2 years, starting from May 21, 2024.\n - Hourly data is available for the most recent six months, while older data is aggregated daily.\n- August 19, 2024:\n - New metrics added to the list\n - `d[x]LevelComplete`, `d[x]CostPerLevelComplete`, `d[x]LevelCompleteRate`\n - New breakdown options added: `eventType`, `eventName`\n - New filter options added: `eventTypes`, `eventNames`\n- August 05, 2024:\n - More post-install days support added.\n - Supported days now include: 0, 1, 3, 7, and 14.\n - Added more post-install days support for the following metrics: `d[x]AdRevenueRoas`, `d[x]IapRoas`, and `d[x]TotalRoas`.\n - New metrics added to the list.\n - `d[x]AdRevenue`, `d[x]IapRevenue`, `d[x]Purchases`, `d[x]UniquePurchasers`, `d[x]Retained`, `d[x]RetentionRate`\n- May 16, 2024: \"Handling Large Data Queries\" section added.\n- January 24, 2024: SKAN endpoint added.\n- January 18, 2024: Added data freshness note to documentation.\n- November 21, 2023: Unity Advertiser Statistics API version 2 released.\n\n# Glossary\n\n## Metrics\n### Basic\n| Metric | Description | Note |\n|---------------------------|----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|\n| starts | The number of times a user starts your ad. | Starts are also known as impressions. |\n| views | The number of times users watched your entire ad. | |\n| clicks | The number of times a user clicks the call-to-action button in your ad. | |\n| installs | The number of users who install your app after watching the ad. | |\n| spend | The advertising budget spent.\t | Spend is calculated by multiplying the number of installs by the cost per install (CPI).|\n| cpi | Cost per install (CPI): the average cost to the advertiser per install. | CPI is calculated by dividing the Spend amount by the number of installs. |\n| ctr | Click 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. |\n| cvr | Conversion 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. |\n| ecpm | The estimated cost in dollars per 1,000 starts (effective cost per mille). | |\n\n### Post-install\nPost-install metrics are provided for specific timeframe after a user installs the app and are represented using the \"Dx\" format, where:\n - \"d\" stands for \"day\".\n - \"x\" is a placeholder for the number of days after install.\n\n Example: \"d7AdRevenue\" represents the ad revenue generated within the 7-day timeframe.\n\n| Metric | Description | Supported Days | Note |\n|---------------------------|--------------------------------------------------------------------------------------|-----------------------|------------------------------------------------------------------------------------------------------|\n| d[x]AdRevenue | Revenue from your ad campaign. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]AdRevenueRoas | Ad revenue return on ad spend. | 0, 1, 3, 7, 14, 21, 28| Ad revenue roas is calculated by dividing the revenue earned by the amount spent on advertising. |\n| d[x]IapRevenue | Revenue from users purchasing in-app items. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]IapRoas | In-app purchase revenue return on ad spend. | 0, 1, 3, 7, 14, 21, 28| IAP roas is calculated by dividing the IAP revenue earned by the amount spent on advertising. |\n| d[x]Purchases | In-app transactions made in your app. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]UniquePurchasers | The number of first-time in-app purchasers within the selected time interval. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]Retained | The number of users continuing to engage with your app for the selected time period. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]RetentionRate | The percentage of users who continue engaging with an app over time. | 0, 1, 3, 7, 14, 21, 28| Retention rate is calculated by dividing the number of retained users by the number of installs. |\n| d[x]TotalRoas | The total return on ad spend (ROAS) within the selected dx timeframe. | 0, 1, 3, 7, 14, 21, 28| Total roas is calculated by adding IAP revenue and ad revenue, then dividing by your spend. |\n| d[x]LevelComplete | The number of users who completed a specified level. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]CostPerLevelComplete | The average cost for a user who completed a specified level. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]LevelCompleteRate | The percentage of users who completed a specified level per install. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]Payer | The number of users who made a payment. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]PayerRate | The percentage of payers per install. | 0, 1, 3, 7, 14, 21, 28| |\n| d[x]CostPerPayer | The average cost for a user who made a payment. | 0, 1, 3, 7, 14, 21, 28| |\n" }, "servers": [ { "url": "https://services.api.unity.com", "description": "Production server" } ], "paths": { "/advertise/stats/v2/organizations/{organizationId}/reports/acquisitions": { "parameters": [ { "$ref": "#/components/parameters/stats.acceptEncoding" }, { "$ref": "#/components/parameters/stats.organizationId" }, { "$ref": "#/components/parameters/stats.start" }, { "$ref": "#/components/parameters/stats.end" }, { "$ref": "#/components/parameters/stats.scale" }, { "$ref": "#/components/parameters/stats.metrics" }, { "$ref": "#/components/parameters/stats.breakdowns" }, { "$ref": "#/components/parameters/stats.filter.appIds" }, { "$ref": "#/components/parameters/stats.filter.campaignIds" }, { "$ref": "#/components/parameters/stats.filter.gameIds" }, { "$ref": "#/components/parameters/stats.filter.creativePackIds" }, { "$ref": "#/components/parameters/stats.filter.creativePackTypes" }, { "$ref": "#/components/parameters/stats.filter.countries" }, { "$ref": "#/components/parameters/stats.filter.platforms" }, { "$ref": "#/components/parameters/stats.filter.eventTypes" }, { "$ref": "#/components/parameters/stats.filter.eventNames" }, { "$ref": "#/components/parameters/stats.format" }, { "$ref": "#/components/parameters/stats.eofMarker" } ], "get": { "summary": "Acquisitions Report", "description": "This endpoint returns Acquisitions reports in CSV format that are under the given organization.\n", "security": [ { "ServiceAccount": [ "advertise.stats.get" ] } ], "operationId": "stats-acquisition", "tags": [ "Acquisitions" ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "example": "Sample request:\ncurl -H \"Authorization: Basic :\" https://services.api.unity.com/advertise/stats/v2/organizations/:organization_id/reports/acquisitions?breakdowns=campaign,country&metrics=clicks,installs,spend&scale=day&start=2020-10-01&end=2020-10-02\n\nSample response:\ntimestamp,campaign id,campaign name,country,clicks,installs,spend \n2020-10-01,\"50ed569d57fe1f324a15fbf7\",\"Campaign #5\",AU,71,30,45\n2020-10-01,\"50eeb7339e10c9d21c0225cb\",\"Campaign #6\",AT,39,19,28.5\n2020-10-01,\"50eeb7339e10c9d21c0225cb\",\"Campaign #6\",AU,16,10,15 \n2020-10-01,\"50eeb7339e10c9d21c0225cb\",\"Campaign #6\",BE,209,120,180\n", "schema": { "$ref": "#/components/schemas/stats.acquisitionsCsvResponseBody" } }, "application/json": { "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 } ] }, "schema": { "$ref": "#/components/schemas/stats.acquisitionsJsonResponseBody" } } } }, "400": { "$ref": "#/components/responses/ValidationError.v2" }, "401": { "$ref": "#/components/responses/AuthenticationError.v2" }, "403": { "$ref": "#/components/responses/AuthorizationError.v2" }, "404": { "$ref": "#/components/responses/NotFoundError.v2" }, "429": { "$ref": "#/components/responses/TooManyRequestsError.v2" }, "500": { "$ref": "#/components/responses/InternalServerError.v1" }, "503": { "$ref": "#/components/responses/ServiceUnavailableError.v2" } } } }, "/advertise/stats/v2/organizations/{organizationId}/reports/skan": { "parameters": [ { "$ref": "#/components/parameters/stats.acceptEncoding" }, { "$ref": "#/components/parameters/stats.organizationId" }, { "$ref": "#/components/parameters/stats.start" }, { "$ref": "#/components/parameters/stats.end" }, { "$ref": "#/components/parameters/stats.scale" }, { "$ref": "#/components/parameters/stats.skanMetrics" }, { "$ref": "#/components/parameters/stats.skanBreakdowns" }, { "$ref": "#/components/parameters/stats.filter.appIds" }, { "$ref": "#/components/parameters/stats.filter.campaignIds" }, { "$ref": "#/components/parameters/stats.filter.gameIds" }, { "$ref": "#/components/parameters/stats.format" }, { "$ref": "#/components/parameters/stats.eofMarker" } ], "get": { "summary": "SKAN Report", "description": "This endpoint returns SKAN reports in CSV format under the given organization.\n", "security": [ { "ServiceAccount": [ "advertise.stats.get" ] } ], "operationId": "stats-skan", "tags": [ "SKAN" ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "example": "Sample request:\ncurl -H \"Authorization: Basic :\" https://services.api.unity.com/advertise/stats/v2/organizations/:organization_id/reports/skan?start=2024-01-15&end=2024-01-16&metrics=starts,installs,spend&scale=day&breakdowns=app\n\ntimestamp,app id,app name,unity app id,starts,installs,spend\n2024-01-15,\"30ed569d57fe1f324a15fbe7\",\"App #1\",\"7f2c8a91-4d3b-4e1f-9a2c-6b5d4e3f2a10\",2894,40,62.5\n2024-01-15,\"30ed569d57fe1f324a15fbe8\",\"App #2\",\"3b9e1c7f-8a2d-4f6e-b4c1-0d9e8f7a6b5c\",1258,16,23.95\n", "schema": { "$ref": "#/components/schemas/stats.acquisitionsCsvResponseBody" } }, "application/json": { "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 } ] }, "schema": { "$ref": "#/components/schemas/stats.acquisitionsJsonResponseBody" } } } }, "400": { "$ref": "#/components/responses/ValidationError.v2" }, "401": { "$ref": "#/components/responses/AuthenticationError.v2" }, "403": { "$ref": "#/components/responses/AuthorizationError.v2" }, "404": { "$ref": "#/components/responses/NotFoundError.v2" }, "429": { "$ref": "#/components/responses/TooManyRequestsError.v2" }, "500": { "$ref": "#/components/responses/InternalServerError.v1" }, "503": { "$ref": "#/components/responses/ServiceUnavailableError.v2" } } } } }, "components": { "securitySchemes": { "ServiceAccount": { "type": "http", "scheme": "basic" } }, "parameters": { "stats.acceptEncoding": { "name": "Accept-Encoding", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "gzip", "deflate" ] } }, "stats.organizationId": { "name": "organizationId", "in": "path", "description": "Unique identifier for an Organization.\n\nPlease use the following steps to look up the organization ID:\n 1. Open the [Acquire Dashboard](https://dashboard.unity3d.com/acquire)\n 2. Select **Settings** from the navigation\n 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`.\n", "example": "5772916123937", "required": true, "schema": { "$ref": "#/components/schemas/stats.organizationId" } }, "stats.start": { "name": "start", "in": "query", "description": "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.", "example": "2023-10-01T13:00:00.000Z", "required": true, "schema": { "$ref": "#/components/schemas/stats.date" } }, "stats.end": { "name": "end", "in": "query", "description": "End time of the data query in `ISO 8601` format. The API includes data up to but not including the end time.", "example": "2023-10-01T14:00:00.000Z", "required": true, "schema": { "$ref": "#/components/schemas/stats.date" } }, "stats.scale": { "name": "scale", "in": "query", "description": "Time resolution of the data.", "example": "hour", "required": true, "schema": { "$ref": "#/components/schemas/stats.scale" } }, "stats.filter.appIds": { "name": "appIds", "in": "query", "description": "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.\n", "required": false, "schema": { "type": "string", "example": "5fbfb6c7fc928924a8827e97,5fbfb6c7fc928924a9971e12" } }, "stats.filter.campaignIds": { "name": "campaignIds", "in": "query", "description": "A comma-separated list of campaign IDs to filter.", "required": false, "schema": { "type": "string", "example": "50ed569d57fe1f324a15fbf7,50eeb7339e10c9d21c0225cb" } }, "stats.filter.gameIds": { "name": "gameIds", "in": "query", "description": "A comma-separated list of target game IDs to filter.", "required": false, "schema": { "type": "string", "example": "A1b2C3d4E5f6,a1B2c3D4e5F6" } }, "stats.filter.creativePackTypes": { "name": "creativePackTypes", "in": "query", "description": "A comma-separated list of creative pack types to filter.\n\n##### Options\n - video\n - playable\n - video+playable\n", "required": false, "schema": { "type": "string", "example": "video,playable" } }, "stats.filter.platforms": { "name": "platforms", "in": "query", "description": "A comma-separated list of platforms to filter.", "required": false, "schema": { "type": "string", "example": "ios,android" } }, "stats.filter.creativePackIds": { "name": "creativePackIds", "in": "query", "description": "A comma-separated list of creative pack IDs to filter.", "required": false, "schema": { "type": "string", "example": "5fbfb6da37106d5ea98d82a7,5fbfb6c7fc928924a9971e12" } }, "stats.filter.eventTypes": { "name": "eventTypes", "in": "query", "description": "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", "required": false, "schema": { "type": "string", "example": "level_complete,in_app_purchase" } }, "stats.filter.eventNames": { "name": "eventNames", "in": "query", "description": "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)", "required": false, "schema": { "type": "string", "example": "finish_lvl_20,buy_10_diamonds" } }, "stats.format": { "name": "format", "in": "query", "description": "The response format. The default is CSV.", "required": false, "schema": { "type": "string", "example": "json", "enum": [ "csv", "json" ] } }, "stats.eofMarker": { "name": "eofMarker", "in": "query", "description": "When set to `true`, appends an end-of-file marker row to CSV responses to indicate that the download is complete.\nThis allows clients to distinguish between complete and partial (truncated) CSV downloads.\n\nThe marker row has the format `#__EOF__,rows=N` followed by empty columns to match the CSV column count.\nIf the EOF marker is present, the download is complete. If it's missing, the download may be partial or incomplete.\n\nThe marker row is only added when:\n- The response format is CSV (not JSON)\n- The response contains data (not empty)\n\n**Example**: For a CSV with 5 columns and 10 data rows, the EOF marker row would be:\n`#__EOF__,rows=10,,,`\n\n**Use case**: When downloading large CSV files, clients can verify download completeness by checking for the EOF marker at the end of the response.\n", "required": false, "schema": { "type": "boolean", "example": true } }, "stats.breakdowns": { "name": "breakdowns", "in": "query", "description": "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. \nWhile metrics give you the overall numbers, breakdowns allow you to see those numbers by different segments. In practice, using a metric \nlike \"installs\" combined with a breakdown by \"country\" would detail how many installs came from each specific country.\n\n##### Options\n - app\n - campaign\n - country\n - creativePack\n - creativePackType\n - osVersion\n - platform\n - sourceAppId\n - store\n - targetGame\n - eventType\n - eventName\n\n#### Split data\nSplit `app` data results in three fields:\n - app id\n - app name\n - 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)\n\nSplit `campaign` data results in two fields:\n - campaign id\n - campaign name\n\nSplit `creativePack` data results in two fields:\n - creative pack id\n - creative pack name\n\nSplit `targetGame` data results in three fields:\n - target id\n - target store id\n - target name\n\n**Note**: Splitting data by too many dimensions may impact response times for querying the API.\nWe 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.\n", "required": false, "schema": { "type": "string", "example": "campaign,country" } }, "stats.skanBreakdowns": { "name": "breakdowns", "in": "query", "description": "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.\nDo not include spaces after the commas. \nWhile metrics give you the overall numbers, breakdowns allow you to see those numbers by different segments.\nIn practice, a metric like \"installs\" combined with a breakdown by \"app\" would detail how many installs came from each specific app.\n\n##### Options\n - app\n - campaign\n - conversionValue\n - targetGame\n\nThe conversion value is the fine-grained conversion value.\nPlease note that breakdown with conversion value does not work with pre-install data (e.g., clicks).\n\n#### Split data\nSplit `app` data results in three fields:\n - app id\n - app name\n - 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)\n\nSplit `campaign` data results in two fields:\n - campaign id\n - campaign name\n\nSplit `conversionValue` data being split by the conversion value\n\nSplit `targetGame` data results in three fields:\n - target id\n - target store id\n - target name\n\n**Note**: Splitting data by too many dimensions may impact response times for querying the API.\n", "required": false, "schema": { "type": "string", "example": "conversionValue" } }, "stats.metrics": { "name": "metrics", "in": "query", "description": "You can specify comma-separated fields to display in your report.\n##### Options\n - starts\n - views\n - clicks\n - installs\n - spend\n - cpi\n - ctr\n - cvr\n - ecpm\n - d0AdRevenue\n - d1AdRevenue\n - d3AdRevenue\n - d7AdRevenue\n - d14AdRevenue\n - d21AdRevenue\n - d28AdRevenue\n - d0AdRevenueRoas\n - d1AdRevenueRoas\n - d3AdRevenueRoas\n - d7AdRevenueRoas\n - d14AdRevenueRoas\n - d21AdRevenueRoas\n - d28AdRevenueRoas\n - d0IapRevenue\n - d1IapRevenue\n - d3IapRevenue\n - d7IapRevenue\n - d14IapRevenue\n - d21IapRevenue\n - d28IapRevenue\n - d0IapRoas\n - d1IapRoas\n - d3IapRoas\n - d7IapRoas\n - d14IapRoas\n - d21IapRoas\n - d28IapRoas\n - d0Purchases\n - d1Purchases\n - d3Purchases\n - d7Purchases\n - d14Purchases\n - d21Purchases\n - d28Purchases\n - d0UniquePurchasers\n - d1UniquePurchasers\n - d3UniquePurchasers\n - d7UniquePurchasers\n - d14UniquePurchasers\n - d21UniquePurchasers\n - d28UniquePurchasers\n - d0Retained\n - d1Retained\n - d3Retained\n - d7Retained\n - d14Retained\n - d21Retained\n - d28Retained\n - d0RetentionRate\n - d1RetentionRate\n - d3RetentionRate\n - d7RetentionRate\n - d14RetentionRate\n - d21RetentionRate\n - d28RetentionRate\n - d0TotalRoas\n - d1TotalRoas\n - d3TotalRoas\n - d7TotalRoas\n - d14TotalRoas\n - d21TotalRoas\n - d28TotalRoas\n - d0LevelComplete\n - d1LevelComplete\n - d3LevelComplete\n - d7LevelComplete\n - d14LevelComplete\n - d21LevelComplete\n - d28LevelComplete\n - d0CostPerLevelComplete\n - d1CostPerLevelComplete\n - d3CostPerLevelComplete\n - d7CostPerLevelComplete\n - d14CostPerLevelComplete\n - d21CostPerLevelComplete\n - d28CostPerLevelComplete\n - d0LevelCompleteRate\n - d1LevelCompleteRate\n - d3LevelCompleteRate\n - d7LevelCompleteRate\n - d14LevelCompleteRate\n - d21LevelCompleteRate\n - d28LevelCompleteRate\n - d0Payer\n - d1Payer\n - d3Payer\n - d7Payer\n - d14Payer\n - d21Payer\n - d28Payer\n - d0PayerRate\n - d1PayerRate\n - d3PayerRate\n - d7PayerRate\n - d14PayerRate\n - d21PayerRate\n - d28PayerRate\n - d0CostPerPayer\n - d1CostPerPayer\n - d3CostPerPayer\n - d7CostPerPayer\n - d14CostPerPayer\n - d21CostPerPayer\n - d28CostPerPayer\n", "required": true, "schema": { "type": "string", "example": "clicks,installs,spend" } }, "stats.skanMetrics": { "name": "metrics", "in": "query", "description": "you can specify comma-separated fields to display in your report.\n##### Options\n - starts\n - views\n - clicks\n - installs\n - spend\n - cpi\n - cvr\n\nThe pre-install data (e.g., clicks) is from devices that support SKAdNetwork.\nInstalls are derived from SKAdNetwork and include re-downloads.\n", "required": true, "schema": { "type": "string", "example": "clicks,installs,spend" } }, "stats.filter.countries": { "name": "countries", "in": "query", "description": "A comma-separated list of country codes to filter.\n\nCountry code in `ISO 3166-1 alpha-2` format.\n", "required": false, "schema": { "type": "string", "example": "AU,CA,AT,BE" } } }, "schemas": { "BasicErrorModel.v1": { "type": "object", "required": [ "title", "status" ], "description": "Referenced from - https://tools.ietf.org/html/rfc7807#page-3\nConsumers MUST use the 'type' string as the primary identifier for the problem type; the 'title' string is advisory and included only for users who are not aware of the semantics of the URI and do not have the ability to discover them (e.g., offline log analysis). Consumers SHOULD NOT automatically dereference the type URI.\nThe \"status\" member, if present, is only advisory; it conveys the HTTP status code used for the convenience of the consumer. Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly. See Section 5 for further caveats regarding its use.\nConsumers can use the status member to determine what the original status code used by the generator was, in cases where it has been changed (e.g., by an intermediary or cache), and when message bodies persist without HTTP information. Generic HTTP software will still use the HTTP status code.\nThe \"detail\" member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information.", "properties": { "title": { "type": "string", "description": "A short, human-readable summary of the problem type. It SHOULD NOT\nchange from occurrence to occurrence of the problem, except for\npurposes of localization (e.g., using proactive content negotiation;\nsee [RFC7231, Section 3.4]).\n\n[RFC7231, Section 3.4]: https://www.rfc-editor.org/rfc/rfc7231#section-3.4\n" }, "details": { "type": "array", "description": "Machine readable service specific errors.", "items": { "type": "object", "example": { "code": "ERROR_CODE_123", "path": "nested.value", "message": "Invalid value" } } }, "requestId": { "type": "string", "format": "uuid", "description": "An identifier Unity uses internally to investigate what happened to a particular request.", "example": "aad109f8-033f-4a24-8b77-5032eb3a6158" }, "detail": { "type": "string", "example": "Something is wrong", "description": "A human-readable explanation specific to this occurrence of the problem." }, "status": { "type": "integer" }, "type": { "type": "string", "description": "Link to the documentation for further information." }, "code": { "type": "integer" } } }, "stats.acquisitionsCsvResponseBody": { "type": "string", "description": "CSV response for reporting endpoints.\n\nThe data returns in CSV format, with the following delimiters:\n - Commas (`,`) separate fields.\n - Periods (`.`) indicate decimals.\n - Double quotes (`\" \"`) indicate text fields.\n - The newline character separates lines within a field.\n \nWhen the `eofMarker` query parameter is set to `true`, an additional row is appended at the end of the CSV response to indicate a complete download:\n - The first column contains `#__EOF__`\n - The second column contains `rows=N` where N is the number of data rows\n - Remaining columns are empty to match the CSV column count\n - Example: `#__EOF__,rows=10,,,` (for a CSV with 5 columns and 10 data rows)\n \n**Important**: The presence of the EOF marker indicates the CSV download is complete. If the marker is missing, the download may be partial or truncated (e.g., due to network interruption or timeout).\n" }, "stats.acquisitionsJsonResponseBody": { "type": "object", "description": "JSON response for reporting endpoints.\n\nThe response is a JSON object containing an array of data rows under the `data` field.\n" }, "stats.date": { "type": "string", "format": "date-time", "description": "UTC date and time.", "example": "2023-01-08T13:16:21.691Z" }, "stats.scale": { "type": "string", "description": "Time resolution of the data.\n\nSummary: This option will provide a general overview or summary of the data. A time interval to the precision of the hour will accompany the data. \nFor example: \"2023-10-16T00/2023-10-16T23\" represents the start and end of the included data.\n\nHour: Data will be accompanied by a timestamp to the precision of the hour. For example: \"2023-10-16T02\" represents 2:00 AM.\n\nDay: With this option, the data comes with a daily timestamp. For example: \"2023-10-16\" signifies the data is for October 16, 2023. \n\nWeek: Data will be accompanied by a timestamp to the precision of the week. For example: \"2023-W42\" represents the 42nd week of 2023.\n\nMonth: Data provided monthly will have a timestamp showing the month and year. For instance: \"2023-10\" would be for the month of October in the year 2023.\n\nThe time is in UTC, uses ISO 8601 format, and each day splits at 00:00 UTC.\n\nPlease be aware that if you request incomplete time interval, the data will be incomplete. An incomplete time interval refers to a time range \nthat does not encompass an entire scale unit, such as a month, week, or day. For example, if you specify a date range from 2023-09-01 to 2023-10-15 and chooses \"month\" scale, \nyou will receive full September data and partial October data.\n", "example": "month", "enum": [ "summary", "hour", "day", "week", "month" ] }, "stats.organizationId": { "type": "string", "pattern": "^[0-9]+$", "description": "Unique identifier for an Organization.", "example": "5772916123937" } }, "responses": { "AuthenticationError.v2": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BasicErrorModel.v1" }, { "type": "object", "properties": { "title": { "example": "Unauthorized" }, "type": { "example": "https://services.docs.unity.com/docs/errors#51" }, "code": { "example": 51 }, "status": { "example": 401 } } } ] } } } }, "AuthorizationError.v2": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BasicErrorModel.v1" }, { "type": "object", "properties": { "title": { "example": "Forbidden" }, "status": { "example": 403 }, "code": { "example": 53 }, "type": { "example": "https://services.docs.unity.com/docs/errors#53" } } } ] } } } }, "InternalServerError.v1": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "code": { "type": "integer", "example": 1 }, "requestId": { "type": "string", "format": "uuid", "description": "Request correlation ID", "example": "aad109f8-033f-4a24-8b77-5032eb3a6158" } } } } } }, "NotFoundError.v2": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BasicErrorModel.v1" }, { "type": "object", "properties": { "title": { "example": "Not Found" }, "status": { "example": 404 }, "code": { "example": 54 }, "type": { "example": "https://services.docs.unity.com/docs/errors#54" } } } ] } } } }, "ServiceUnavailableError.v2": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BasicErrorModel.v1" }, { "type": "object", "properties": { "title": { "example": "Service Unavailable" }, "status": { "example": 503 }, "code": { "example": 3 }, "type": { "example": "https://services.docs.unity.com/docs/errors#3" } } } ] } } } }, "TooManyRequestsError.v2": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BasicErrorModel.v1" }, { "type": "object", "properties": { "title": { "example": "Too Many Requests" }, "status": { "example": 429 }, "code": { "example": 50 }, "type": { "example": "https://services.docs.unity.com/docs/errors#50" } } } ] } } } }, "ValidationError.v2": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BasicErrorModel.v1" }, { "type": "object", "properties": { "title": { "example": "Bad Request" }, "status": { "example": 400 }, "type": { "example": "https://services.docs.unity.com/docs/errors#55" }, "code": { "example": 55 } } } ] } } } } } } } ````