Make your first API call
This page explains how to make your first API call to Apps and Games.
API call pattern
The following diagram shows the API call pattern used to create a new report template, schedule the custom report, and retrieve failure data.
This list provides more details about the API call pattern diagram.
- The client application can define the custom report schema/template by calling the Create Report Query API. Alternately, you can use a report template
(QueryId)from the list of system queries. - On success, the Create Report Template API returns the
QueryId. - The client application then calls the Create Report API using the
QueryIDalong with the report start date, Repeat Interval, Recurrence, and an optional Callback URI. - On success, the Create Report API returns the
ReportID. - The client application calls the Status API to get the status of the report.
- The client application then uses the Get Report Executions API to query the status of the report with the
Report IDand date range. - On success, the report download link is returned and the application can initiate download of the data.
Specify report query language
Although we provide system queries you can use to create reports, you can also create your own queries based on your business needs. To learn more about custom queries, see Custom query specification.
Authentication
First, onboard to the Partner Center account by completing prerequisites for using the Microsoft Store analytics API. Next, obtain a Microsoft Entra access token. Please follow Step 1 and Step 2 only. Step 3 is redundant for this flow.
Programmatic API call
After you obtain the Microsoft Entra Token as described in the previous section, follow these steps to create your first programmatic access report.
Data can be downloaded from the following datasets (datasetName):
| Report Name | Dataset Name in API |
|---|---|
| Acquisition | Acquisitions |
| Add-on acquisition | AddOnAcquisitions |
| Channels and Conversion | ChannelsAndConversions |
| Gamepass Usage | GamePass |
| Gamepass Performance | GamePassPurchase |
| Health: Crashes and Events | HealthFailureHits |
| Installs | Installs |
| Ratings | Ratings |
| Reviews | Reviews |
| Sustainability | Sustainability |
| Usage-Daily | UsageDaily |
| Usage-Monthly | UsageMonthly |
| Wishlist | Wishlist |
| Events Engagement | Xevents_Metrics |
| Pricing Promotions - Flexible | Xprice_Flexible_Offer |
| Pricing Promotions - Targeted | Xprice_Targeted_Offer |
The following sections show examples of how to programmatically access the content from the Acquisition dataset.
Make a REST call using the Get Datasets API
The API response provides the dataset name from where you can download the report. For the specific dataset, the API response also provides the list of selectable columns that can be used for your custom report template.
Create report query API
This API helps to create custom queries that define the dataset from which columns and metrics need to be exported. The API provides the flexibility to create a new reporting template based on your business needs.
You can also use the system queries we provide. When custom report templates aren't needed, you can call the Create Report API directly using the QueryIds of the system queries we provide.
Request example
curl
--location
--request GET https://manage.devcenter.microsoft.com/consumer/insights/v1.1 /ScheduledDataset' \
--header 'Authorization: Bearer <AzureADToken>'
Response example
{
"value": [
{
"columnFilters": {},
"aggregationToDateRangeMapping": {
"Hourly": "LAST_72_HOURS",
"Daily": "LAST_30_DAYS,LAST_3_MONTHS",
"Weekly": "LAST_6_MONTHS,LAST_12_MONTHS",
"Monthly": "LAST_2_YEARS,LAST_3_YEARS,LAST_4_YEARS"
},
"datasetName": "Acquisitions",
"selectableColumns": [
"TitleId",
"ProductId",
"XboxProductId",
"ProductTypeName",
"TitleName",
"CatalogId",
"SandboxId",
"SkuId",
"SkuTypeName",
"SkuDisplayName",
"AvailabilityId",
"RegionName",
"CountryName",
"Market",
"PaymentType",
"StoreClientName",
"StoreClientCategory",
"ParentProductName",
"ParentProductId",
"XboxParentProductId",
"AcquisitionType",
"PurchaseTaxType",
"LocalCurrencyCode",
"SupportedPlatform",
"Age",
"Gender",
"OsVersion",
"DeviceType",
"DateStamp"
],
"availableMetrics": [
"PurchaseQuantity",
"PurchasePriceUSDAmount",
"PurchaseTaxUSDAmount",
"PurchasePriceLocalAmount",
"PurchaseTaxLocalAmount"
],
"availableDateRanges": [
"LAST_72_HOURS",
"LAST_30_DAYS",
"LAST_3_MONTHS",
"LAST_6_MONTHS",
"LAST_12_MONTHS",
"LAST_2_YEARS",
"LAST_3_YEARS",
"LAST_4_YEARS"
],
"minimumRecurrenceInterval": 1
}
}
Create the custom query
In this step, we create a custom query for the report we want. This query created is used every time there's a report required (execute now or schedule).
Request example
curl
--location
--request POST ' https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries' \
--header ' Authorization: Bearer <AzureAD_Token>' \
--header 'Content-Type: application/json' \
--data-raw
'{
"Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily",
"Name": "Consumer public API Create query",
"Description": "Acquisition query creation."
}'
Response example
{
"value": [
{
"ProductInfo": {
"productGroupId": "",
"productId": "all",
"productIdDbColumnName": "ProductId"
},
"queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615",
"name": "Consumer public API Create query",
"description": "Acquisition query creation",
"query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily",
"type": "userDefined",
"user": "",
"createdTime": "2024-03-26T11:26:48Z"
}
],
"totalCount": 1,
"message": "Query created successfully",
"statusCode": 200
}
On successful execution of the query, a queryId is generated that needs to be used to generate the report.
Get query
Lists all the queries available. The existing query created in the above step should reflect here.
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries' \
--header 'Authorization: Bearer <token> \
Response example
{
"value": [
{
"ProductInfo": {
"productGroupId": "",
"productId": "all",
"productIdDbColumnName": "ProductId"
},
"queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615",
"name": "Consumer public API Create query",
"description": "Acquisition query creation",
"query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily",
"type": "userDefined",
"user": "",
"createdTime": "2024-03-26T11:26:48Z"
},
{
"ProductInfo": {
"productGroupId": "",
"productId": "9PDC2J734M08",
"productIdDbColumnName": "ProductId"
},
"queryId": "724c796e-ea64-438f-b784-f2e284349d2f",
"name": "Acquisition_Daily_30days_next2months",
"description": null,
"query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, DateStamp, PurchaseQuantity, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily",
"type": "userDefined",
"user": "",
"createdTime": "2024-01-23T17:21:42Z"
}
],
"totalCount": 2,
"message": "Queries fetched successfully",
"statusCode": 200
}
Create an instant async report
In this step, we use the previously generated QueryId to create the report. The below query is used to execute now the report. The report generation is async and requires a separate API call to fetch the report.
Request example
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \
--header 'Authorization: Bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
"Description": "Acquisition report",
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615",
"ReportName": "Create Report - Acquisition",
"executeNow": true
}'
Response example
{
"value": [
{
"productInfo": {
"productGroupId": "",
"productId": "all",
"productIdDbColumnName": "ProductId"
},
"reportId": "b58f9802-b118-485f-a0f1-edc273dea275",
"reportName": "Create Report - Acquisition",
"description": " Acquisition report ",
"queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615",
"query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily",
"user": "",
"createdTime": "",
"modifiedTime": null,
"executeNow": true,
"queryStartTime": null,
"queryEndTime": null,
"startTime": "2024-03-26T11:33:16Z",
"reportStatus": "Active",
"recurrenceInterval": -1,
"recurrenceCount": 1,
"callbackUrl": null,
"callbackMethod": null,
"format": "csv",
"endTime": "2024-03-26T11:33:16Z",
"totalRecurrenceCount": 1,
"nextExecutionStartTime": null
}
],
"totalCount": 1,
"message": "Report created successfully",
"statusCode": 200
}
The reportId: 'execution' is generated. This ID needs to be used to schedule a download of the report.
Note
For details about the totalRecurrenceCount field, see Understand the totalRecurrenceCount field for scheduled reports.
Download the instant report
Request example
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/b58f9802-b118-485f-a0f1-edc273dea275' \
--header 'Authorization: Bearer <token>' \
Response example
{
"value": [
{
"executionId": "28016f06-6bbf-459e-ba30-429da6910192",
"reportId": "b58f9802-b118-485f-a0f1-edc273dea275",
"recurrenceInterval": -1,
"recurrenceCount": 1,
"callbackUrl": null,
"callbackMethod": null,
"format": "csv",
"executionStatus": "Completed",
"reportLocation": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv",
"reportAccessSecureLink": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv? <SAS token> ",
"reportExpiryTime": null,
"reportGeneratedTime": "2024-03-26T11:46:19Z",
"endTime": "2024-03-26T11:33:16Z",
"totalRecurrenceCount": 1,
"nextExecutionStartTime": null
}
],
"totalCount": 1,
"message": null,
"statusCode": 200
}
The reportAccessSecureLink can be invoked to download the report.
Create a schedule report
The API calls help to create a schedule report.
Request
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \
--header 'Authorization: Bearer <token> \
--header 'Content-Type: application/json' \
--data '{
"Description": "Creating a scheduled report",
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615",
"ReportName": "Create scheduled report - Acquisition",
"StartTime": "2024-03-26T18:00:19Z",
"RecurrenceCount": 49,
"RecurrenceInterval": 1
}'
Response
{
"value": [
{
"productInfo": {
"productGroupId": "",
"productId": "all",
"productIdDbColumnName": "ProductId"
},
"reportId": "5e49796b-8146-4d98-9dde-aa14d2f78f0f",
"reportName": "Create scheduled report - Acquisition",
"description": "Acquisition description",
"queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615",
"query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily",
"user": "",
"createdTime": "2024-03-26T11:38:20Z",
"modifiedTime": null,
"executeNow": false,
"queryStartTime": null,
"queryEndTime": null,
"startTime": "2024-03-26T18:00:19Z",
"reportStatus": "Active",
"recurrenceInterval": 1,
"recurrenceCount": 49,
"callbackUrl": null,
"callbackMethod": null,
"format": "csv",
"endTime": "2024-03-28T18:00:19Z",
"totalRecurrenceCount": 49,
"nextExecutionStartTime": "2024-03-26T17:00:19Z"
}
],
"totalCount": 1,
"message": "Report created successfully",
"statusCode": 200
}
Get report status and download details
Now that we've created a report, we'll make an API call to get the report status and its downloadable link so that the report can be downloaded on to the client. To make this call, we're querying with the same reportId generated in the previous step.
Request
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/3b6c1ec2-53c2-48f6-9c9b-a46e5ca69d7d' \
--header 'Authorization: Bearer<token>' \
Response
{
"value": [
{
"executionId": "28016f06-6bbf-459e-ba30-429da6910192",
"reportId": "5e49796b-8146-4d98-9dde-aa14d2f78f0f",
"recurrenceInterval": -1,
"recurrenceCount": 1,
"callbackUrl": null,
"callbackMethod": null,
"format": "csv",
"executionStatus": "Completed",
"reportLocation": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv",
"reportAccessSecureLink": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv? <SAS token> ",
"reportExpiryTime": null,
"reportGeneratedTime": "2024-03-26T11:46:19Z",
"endTime": "2024-03-26T11:33:16Z",
"totalRecurrenceCount": 1,
"nextExecutionStartTime": null
}
],
"totalCount": 1,
"message": null,
"statusCode": 200
}
Create a schedule report with webhook
The webhook functions as an endpoint that is invoked as soon as the report is ready. The callbackURL parameter needs to be provided.
Partners need to write their webhook handler. In the previous example, once the report is ready, the 'https://msnotify.com' is invoked as a notification. On the invocation, partners can get the list of scheduled report and their statuses, and then use the above-mentioned APIs to download the file.
Request
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \
--header 'Authorization: Bearer<token>' \
--header 'Content-Type: application/json' \
--header 'Cookie: ApplicationGatewayAffinity=3ebb3a6588e1f91ad543ccd7cdf31ec0; ApplicationGatewayAffinityCORS=3ebb3a6588e1f91ad543ccd7cdf31ec0' \
--data '{
"Description": "Acquisition report",
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615",
"ReportName": "Create scheduled report - Acquisition",
"StartTime": "2024-03-26T18:00:19Z",
"RecurrenceCount": 49,
"RecurrenceInterval": 1,
"callbackURL": "https://msnotify.com",
"callbackMethod": "get"
}'
API Documentation
Refer to the OpenAPI specification. Paste the contents of the specification in Public Swagger editor to view the APIs and generate clients in preferred languages (C#, python, etc.) to consume the APIs.
Important
This API has default query parameters set for executionStatus=Completed and getLatestExecution=true. Hence, calling the API before the first successful execution of the report will return a 404 error. Pending executions can be obtained by setting executionStatus=Pending.