````json { "openapi": "3.0.0", "x-publicDocumentationRedocOptions": [ "no-auto-auth", "max-displayed-enum-values=\"10\"" ], "info": { "title": "Advertising Statistics API", "version": "v1.0 deprecated", "contact": { "name": "Unity Ads Support", "email": "unityads-support@unity3d.com" }, "description": "
\n⚠ IMPORTANT: This API version is deprecated and will no longer be available after June 2, 2025. Please migrate to the latest version by referring to this link.\n
\n\n# 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## SKAdNetwork conversion\nThe Statistics API now allows advertisers to start to receive SKadNetwork conversion value data. This supports using SKAd conversion values:\n\n* as a splitBy dimension as skadConversionValue.\n* as a filter via the skadConversionValues parameter.\n\nThis functionality is in addition to the recently launched SKAdNetwork install reporting. It's provided to assist advertisers who wish to test the new SKAdNetwork conversion values throughout March 2021, to prepare for Apple's anticipated roll-out of the Apple ATT for iOS14.\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## Change Log\n* June 1, 2023: Updated data retention time and removed support of Reach Extension field.\n* May 10, 2023: Documented data retention and country limitation of the SKAd-specific fields.\n* August 2, 2021: First draft of the version 1 of the Unity Advertising Statistics API.\n\n\n# Authentication\nUsing the Unity Ads Statistics API requires an API key token. You can generate an API key token from dashboard by selecting **Settings** from the left navigation bar.\n\n**Note**: The API key is generated for an specific username. If that username is removed from the organization, that API key will be automatically revoked. Please be aware of this if you use the API key as part of an integration with a 3rd party or any other business intelligence solution.\n\nYou can use the key token in two ways:\n1. Place the key token in the GET request URL `apikey` parameter. For example:\n```\nhttps://stats.unityads.unity3d.com/organizations/:organization_id/reports/acquisitions?apikey=\n```\n\n2. Place the key token in the `Authorization` header of the GET request, prefixed with `Bearer`. For example:\n```\ncurl -H \"Authorization: Bearer \" https://stats.unityads.unity3d.com/organizations/:organization_id/reports/acquisitions\n```\n\n# Rate Limits\nThe API has rate limiting in place. The rate limit is 1 request every 3 seconds per IP address.\n\n# Data Retention\nThe Statistics API will show data from up to 6 months ago, starting from July 2023.\n" }, "servers": [ { "url": "https://stats.unityads.unity3d.com", "description": "Production server" } ], "paths": { "/organizations/{organizationId}/reports/acquisitions": { "parameters": [ { "$ref": "#/components/parameters/stats.organizationId" }, { "$ref": "#/components/parameters/stats.start" }, { "$ref": "#/components/parameters/stats.end" }, { "$ref": "#/components/parameters/stats.scale" }, { "$ref": "#/components/parameters/stats.splitBy" }, { "$ref": "#/components/parameters/stats.fields" }, { "$ref": "#/components/parameters/stats.filter.campaignSets" }, { "$ref": "#/components/parameters/stats.filter.campaigns" }, { "$ref": "#/components/parameters/stats.filter.targets" }, { "$ref": "#/components/parameters/stats.filter.adTypes" }, { "$ref": "#/components/parameters/stats.filter.countries" }, { "$ref": "#/components/parameters/stats.filter.stores" }, { "$ref": "#/components/parameters/stats.filter.platforms" }, { "$ref": "#/components/parameters/stats.filter.osVersions" }, { "$ref": "#/components/parameters/stats.filter.creativePacks" }, { "$ref": "#/components/parameters/stats.filter.sourceAppIds" }, { "$ref": "#/components/parameters/stats.filter.skadConversionValues" } ], "get": { "deprecated": true, "summary": "Acquisitions Report", "description": "This endpoint returns Acquisitions reports in CSV format that are under the given organization.\n", "security": [ { "ApiKeyAuth": [] } ], "operationId": "stats-acquisition", "tags": [ "Acquisitions" ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "example": "timestamp,campaign set id,campaign set name,country,clicks,installs,spend \n2013-03-01T00:00:00.000Z,50ed569d57fe1f324a15fbf7,\"Campaign set #5\",AU,71,30,45\n2013-03-01T00:00:00.000Z,50ed569d57fe1f324a15fbf7,\"Campaign set #5\",CA,129,88,132\nCONFIDENTIAL, Unity Technologies 2017 Advertiser Stats API2013-03-01T00:00:00.000Z,50ed569d57fe1f324a15fbf7,\"Campaign set#5\",US,1745,855,1282.5\n2013-03-01T00:00:00.000Z,50eeb7339e10c9d21c0225cb,\"Campaign set#6\",AT,39,19,28.5\n2013-03-01T00:00:00.000Z,50eeb7339e10c9d21c0225cb,\"Campaign set #6\",AU,16,10,15 \n2013-03-01T00:00:00.000Z,50eeb7339e10c9d21c0225cb,\"Campaign set #6\",BE,209,120,180\n", "schema": { "$ref": "#/components/schemas/stats.acquisitionsResponseBody" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "403": { "$ref": "#/components/responses/forbiddenRequest" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "query", "name": "apikey" } }, "parameters": { "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 ID`.\n", "example": "5d9705cdc23ff56026eed4c8", "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.", "example": "2021-07-28T13:16:21.691Z", "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.", "example": "2021-08-21T13:16:21.691Z", "required": true, "schema": { "$ref": "#/components/schemas/stats.date" } }, "stats.scale": { "name": "scale", "in": "query", "description": "Time resolution of the data.", "example": "hour", "required": false, "schema": { "$ref": "#/components/schemas/stats.scale" } }, "stats.filter.campaignSets": { "name": "campaignSets", "in": "query", "description": "A comma-separated list of campaign set IDs to filter.", "required": false, "schema": { "type": "string", "example": "5fbfb6c7fc928924a8827e97,5fbfb6c7fc928924a9971e12" } }, "stats.filter.campaigns": { "name": "campaigns", "in": "query", "description": "A comma-separated list of campaign IDs to filter.", "required": false, "schema": { "type": "string", "example": "5fbfb6da37106d5ea98d82a7,5fbfb6c7fc928924a9971e12" } }, "stats.filter.targets": { "name": "targets", "in": "query", "description": "A comma-separated list of target game IDs to filter.", "required": false, "schema": { "type": "string", "example": "A1b2C3d4E5f6,a1B2c3D4e5F6" } }, "stats.filter.adTypes": { "name": "adTypes", "in": "query", "description": "A comma-separated list of ad types to filter.\n\n##### Options\n - video\n - playable\n - video+playable\n", "required": false, "schema": { "type": "string", "example": "video,playable" } }, "stats.filter.stores": { "name": "stores", "in": "query", "description": "A comma-separated list of app stores to filter.\n##### Options\n - apple\n - google\n", "required": false, "schema": { "type": "string", "example": "apple,google" } }, "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.osVersions": { "name": "osVersions", "in": "query", "description": "A comma-separated list of operating system versions to filter.", "required": false, "schema": { "type": "string", "example": "1.0.0,2.1.0" } }, "stats.filter.creativePacks": { "name": "creativePacks", "in": "query", "description": "A comma-separated list of creative packs to filter.", "required": false, "schema": { "type": "string", "example": "5fbfb6da37106d5ea98d82a7,5fbfb6c7fc928924a9971e12" } }, "stats.filter.sourceAppIds": { "name": "sourceAppIds", "in": "query", "description": "A comma-separated list of source app IDs to filter. \nThis ID is an identifier derived from the game's app store page. \nPrior to migration, this was called source_id or source_game_id. \nThis identifier is an alphanumeric, 12-character case-sensitive string.\n\n**Note**: The identifiers source_id and source_game_id have been deprecated. \nThey have been replaced with SourceAppID (source_app_id). \nWhile the deprecated source_game_id was an integer, the identifier SourceAppID (source_app_id)\nis a case-sensitive, 12-character, alphanumeric string. For more information, refer to Source bidding.\n", "required": false, "schema": { "type": "string", "example": "A1b2C3d4E5f6,a1B2c3D4e5F6" } }, "stats.filter.skadConversionValues": { "name": "skadConversionValues", "in": "query", "description": "A comma-separated list of SKAdNetwork conversion values to filter. These values must be integers between 0 and 63.", "required": false, "schema": { "type": "string", "example": "0,12,55" } }, "stats.splitBy": { "name": "splitBy", "in": "query", "description": "you can specify a comma-separated list of dimensions by which to split data.\n\n##### Options\n - campaignSet\n - creativePack\n - adType\n - campaign\n - target\n - sourceAppId\n - store\n - country\n - platform\n - osVersion\n - skadConversionValue\n", "required": false, "schema": { "type": "string", "example": "campaignSet,adType,store" } }, "stats.fields": { "name": "fields", "in": "query", "description": "you to specify comma-separated fields to display in your report.\n\n#### SKAD specific fields\n - **skadInstalls**:\tInstalls from Apple’s SKAdNetwork.\n - **skadCpi**:\tCPI calculated based on installs from Apple’s SKAdNetwork.\n - **skadConversion**:\tConversion calculated based on installs from Apple’s SKAdNetwork.\n\n**Notes**:\n - SKAd specific fields are not available by default in the response and therefore should be explicitly specified in the fields parameter if required.\n - In addition, fields above will not be available for the country, creativePack, adType and osVersion filters since we do not get this granularity of data within the SKAd postbacks.\n\n##### Options\n - timestamp\n - campaignSet\n - creativePack\n - adType\n - campaign\n - target\n - sourceAppId\n - store\n - country\n - platform\n - osVersion\n - starts\n - views\n - clicks\n - installs\n - spend\n - skadInstalls\n - skadCpi\n - skadConversion\n", "required": false, "schema": { "type": "string", "example": "timestamp,campaignSet,osVersion", "default": "all" } }, "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": "US,FI,RU" } } }, "schemas": { "stats.acquisitionsResponseBody": { "type": "string", "description": "CSV response of Acquisitions Report endpoint.\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\n#### Split data\n\nSplit `campaignSet` data results in two fields:\n - campaign set id\n - campaign set name\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 `target` data results in three fields:\n - target id\n - target store id\n - target name\n\n\n**Note**: Splitting data by too many dimensions may impact response times for querying the API.\nTo avoid lagging or timeouts, we recommend querying 1 day of data at a time when splitting by `sourceAppId` and `country`.\n" }, "stats.date": { "type": "string", "format": "date-time", "description": "UTC date and time.", "example": "2021-07-28T13:16:21.691Z" }, "stats.scale": { "type": "string", "description": "Time resolution of the data.", "example": "month", "default": "all", "enum": [ "all", "hour", "day", "week", "month", "quarter", "year" ] }, "stats.organizationId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Unique identifier for an Organization.", "example": "5eb26a338a232100e4bb5893" } }, "responses": { "badRequest": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "parameters": { "type": "array", "items": { "type": "object", "example": { "start": "expected with format YYYY-MM-DDThh:mm:ss" } } } } } } } } } }, "forbiddenRequest": { "description": "Forbidden request", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "parameters": { "type": "array", "items": { "type": "object", "example": { "apikey": "access verification error" } } } } } } } } } } } } } ````