Make your first API call
This page explains how to make your first API call to Apps and Games.
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
QueryID
along 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 ID
and date range. - On success, the report download link is returned and the application can initiate download of the data.
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.
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.
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.
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.
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.
curl
--location
--request GET https://manage.devcenter.microsoft.com/consumer/insights/v1.1 /ScheduledDataset' \
--header 'Authorization: Bearer <AzureADToken>'
{
"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
}
}
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
).
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."
}'
{
"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.
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> \
{
"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
}
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.
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
}'
{
"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.
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/b58f9802-b118-485f-a0f1-edc273dea275' \
--header 'Authorization: Bearer <token>' \
{
"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.
The API calls help to create a schedule report.
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
}'
{
"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
}
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.
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/3b6c1ec2-53c2-48f6-9c9b-a46e5ca69d7d' \
--header 'Authorization: Bearer<token>' \
{
"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
}
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.
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"
}'
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
.