Data Plane Endpoint
If you are using a Dedicated environment, this endpoint will be accessible through your company's Reporting API endpoint. See Data Plane Management for more details.
Auth scope: Reporting API Key or Aggregate Reporting API Key
- Aggregate Reporting API Key is not authorized to pull reports with the user_id group
- Aggregate Reporting API Key is not authorized to pull reports with unattributed users
Use Cases
The statistics API is very powerful and can be used for many different purposes. Here are a few common applications that we would like to highlight
- Unifying attribution data with in-house analytics and BI tools
It is common for larger games to create custom dashboards to track key performance indicators at a glance. Integration with the stats api enables you to include your user acquisition data alongside your other key metrics. Additionally, with Gamesight statistics warehoused you can perform deeper analysis and enhance your learning. - Tagging users by attribution source in-game
Gamesight strives to provide meaningful information about which sources are providing your most valuable users, but sometimes there are metrics that you wish to use to determine player quality that Gamesight doesn't have access to. In these scenarios, the stats API can be used to provide information on attributed source by user_id. This will enable you to attach attribution data to your users so you can run custom user scoring by campaign. - Evaluating campaign performance using custom metrics
Similar to tagging users by attributed source, you may want to use automated methods for evaluating your campaign performance. The stats api's real-time data enables you to react quickly to changes in campaign performance so you can most effectively spend your marketing budgets.
Fields
The following fields are supported.
{
"fields": [
// Touchpoint stats as directly measured by Gamesight
"impressions",
"impressions_unique",
"clicks",
"clicks_unique",
"click_through_rate",
"cost_amount",
"cost_currency",
// Stats as reported by ad platforms (FB/Google/etc)
// Note that these stats are only available for some platforms
// and some combination of dimensions
"network_impressions",
"network_clicks",
"network_click_through_rate",
"network_cost_amount",
"network_cost_currency",
// Display metrics merge together the network reported and Gamesight-measured
// stats, prioritizing Network stats when available.
"display_impressions",
"display_clicks",
"display_click_through_rate",
"display_cost_amount",
"display_cost_currency",
// Goal stats show the number of attributed goal triggers
"goals",
"goal_rate",
"goal_revenue_amount",
"goal_revenue_currency",
// Steam UTM Analytics (requires integration to be enabled)
"steam_total_visits",
"steam_tracked_visits",
"steam_wishlists",
"steam_purchases",
"steam_activations",
]
}
Groups
The following fields can be included in the grouping for the report. If you request a field in the grouping it will also be returned as one of the fields in the results.
{
"groups": [
"user_id",
"game_id",
"team_id",
"network",
"campaign",
"ad_group",
"ad",
"triggered_at_date",
"triggered_at_hour",
"country",
"browser",
"platform",
"touchpoint_type",
"touchpoint_os_family",
"touchpoint_device_brand",
"ad_type",
"placement",
"keyword",
"creative",
"site_id",
"sub_site_id",
"sub1",
"sub2",
"sub3",
"sub4",
"sub5",
"sub6",
"sub7",
"sub8",
"sub9",
"sub10",
]
}
Note if you group by user_id all other groupings will be applied automatically since each value is unique on a per-user basis (except for triggered_at_date, please include this grouping separately if desired). We recommend using the user_id grouping when you want to pull attach source data about your users in your BI system.
Additionally, the clicked_at_date group will group your statistics on the date of the attributed click, not the date that events occurred.
Grouping Ad Platform-Reported Stats
If platform-reported costs, impressions, or clicks are not being returned, try reducing the granularity of your API call. For example, ad platform costs are rarely broken down by sub ID, so including these groupings in your API call will return empty cost fields.
Filters
Each of the following fields may be used to filter the results of a stats request.
{
"filters": {
"user_ids": ["user1", "user2"],
"team_ids": [12345],
"networks": ["facebook"],
"campaigns": ["test_campaign"],
"ad_groups": ["ad-grou-1"],
"ads": ["my-ad"],
"sub1": ["arbitrary"],
"sub2": ["arbitrary"],
"sub3": ["arbitrary"],
"sub4": ["arbitrary"],
"sub5": ["arbitrary"],
"countries": ["CA", "DE"], // ISO 3166-1 alpha-2
"goal_type_ids": [12345],
"start_triggered_at_date": "2000-01-01",
"end_triggered_at_date": "2001-01-01",
}
}
Query Builder
The best way to produce a request payload for the /stats endpoint in the Reporting API is to use the Console UI to build your report. This will enable you to play with your dimensions, groups, and filters in an interactive way and then reproduce those results through the API.
Copy API Request option on the Console reports page
Once you have the report formatted as you would like, you can use the "Copy API Request" button which will copy the request payload for your current report to your clipboard. You can then take this and directly use it against the /stats API to retrieve the same report programmatically.
Response Data Format
You can find an annotated data dictionary for the response model for this API below. This document provides data types and field descriptions for all supported fields in the Stats API response.
