Share via


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.

Diagram of the high-level flow of the API call pattern.

This list provides more details about the API call pattern diagram.

  1. 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.
  2. On success, the Create Report Template API returns the QueryId.
  3. 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.
  4. On success, the Create Report API returns the ReportID.
  5. The client application calls the Status API to get the status of the report.
  6. The client application then uses the Get Report Executions API to query the status of the report with the Report ID and date range.
  7. 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.