Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
[This article is prerelease documentation and is subject to change.]
Learn how to submit, poll, and download Copilot Credit usage reports with Power Automate, the Power Platform CLI, and PowerShell, and then act on the report rows.
The Copilot Credit usage reports API lets you download the same Copilot Credit entitlement and consumption data available in the Power Platform admin center. Use this data to automate decisions, combine it with other data sources, or maintain a long-term history beyond the 30-day reporting window.
Important
The usage reports API is in public preview. Sovereign clouds aren't currently supported. Preview features aren't meant for production use and might have restricted functionality. Preview features are subject to a separate supplemental terms of use
Report generation is asynchronous. Every client in this tutorial follows the same three steps:
- Submit a report request. The service returns
202 Acceptedwith aLocationheader (the operation-status URL) and aRetry-Afterheader. - Poll the operation until its
statusisSucceededorFailed. Follow the polling interval specified byRetry-After. The status API returns200 OKeven while generation is in progress (status: Running), so check the response body rather than treating HTTP 200 as confirmation that the report is ready. - Download the generated file, and then iterate through the rows. The REST example follows the operation response's
LocationURL; the connector and CLI examples pass the returnedfileNameto their download action or command.
In this tutorial, learn how to:
- Download a usage report in Power Automate or Copilot Studio workflows by using the same Power Platform for Admins V2 connector actions and steps.
- Download a usage report from PowerShell by using the Power Platform CLI (
pac). - Download a usage report from PowerShell by calling the Power Platform API directly.
Choose a report
By default, all examples in this tutorial use the FeatureDetailsPerResource report with Summary granularity and request the previous 14 complete UTC days, ending yesterday (UTC). Choose a different report or granularity as needed.
| Report | Use it to | Credit columns |
|---|---|---|
FeatureDetailsPerResource |
View Copilot Credit consumption by agent or resource, environment, product, and feature. | BilledCredits, NonBilledCredits |
BillingDetailsPerEnvironment |
View entitlement and consumption by environment, entitlement, and billing policy, including prepaid and pay-as-you-go consumption. | CapacityPackCreditsConsumed, PayGoConsumedQuantity |
| Granularity | Rows returned |
|---|---|
Daily |
One row per day for each combination of report dimensions. Includes the date column. |
Summary |
Consumption summed across the requested dates for each combination of report dimensions. The date column is omitted. |
For the complete list of columns in each report, see Download Licensing Report File: Report file schemas.
Note
Column names in both CSV and JSON output are case-sensitive. For example, read the agent ID as ResourceID, the agent name as ResourceName, and billed credits as BilledCredits. The threshold examples evaluate each report row independently; they don't aggregate all rows for an agent.
Prerequisites
- A Microsoft Entra user account with one of these roles in your tenant: Global Administrator, Power Platform Administrator, or Dynamics 365 Administrator. The usage reports API supports delegated (user) authentication only; application-only (service principal) tokens aren't supported.
- Copilot Credit consumption in your tenant during the selected time range.
- The tools for the client you choose:
| Client | What you need |
|---|---|
| Power Automate | A Power Automate license that includes standard connectors, and permission to create a Power Platform for Admins V2 connection with an OAuth Connection authentication type. |
| Copilot Studio workflows | Access to Copilot Studio with permission to create workflows, a Power Platform for Admins V2 connection with an OAuth Connection authentication type, and sufficient Copilot Credits to run the workflow. |
| Power Platform CLI | PowerShell 7 and the latest Microsoft Power Platform CLI. |
| PowerShell (REST) | PowerShell 7 and the Azure CLI. |
Handle service protection responses
Report submissions can return 429 Too Many Requests when service protection is enforced. A rejected submission doesn't start a report.
To reduce unnecessary submissions:
- Schedule reports (for example, once a day or once a week) instead of generating them on demand in a tight loop.
- Reuse a downloaded file instead of submitting the same report again.
- If the service supplies
Retry-Afterwith a429response, wait at least that long before submitting another request.
For details, see Generate Licensing Report: Tenant-wide service protection limits.
Download a usage report and act on the results
Use the tabs in the following section to choose a client. Each example submits a FeatureDetailsPerResource request, polls until the operation finishes, downloads the file, and then lists every row where BilledCredits plus NonBilledCredits is greater than 1,000. The threshold applies to individual rows, not cumulative consumption per agent. For example, two rows of 600 credits for the same agent aren't selected, even though their combined total is 1,200. Separate rows can represent different products, features, channels, knowledge sources, tools, models, scenarios, or environments.
Note
A new action for the Power Platform for Admins V2 connector is scheduled to roll out in December 2026. It will combine report request submission, status polling, and report download in a single action for both Power Automate and Copilot Studio workflows, eliminating the need to manage polling in your workflow.
Note
Support for requesting reports in JSON format through the connector is also scheduled to roll out in December 2026. The connector currently generates reports in CSV format by default. The JSON-based connector example below requires this upcoming support.
This example builds a scheduled cloud flow that runs every Monday, downloads a report for the previous 14 complete UTC days, and emails a table of agents whose report rows exceed the consumption threshold. It uses three actions from the Power Platform for Admins V2 connector.
The steps in the following section apply to both Copilot Studio workflows and Power Automate cloud flows. The instructions for creating the flow use Power Automate's navigation. If you're using Copilot Studio, create a scheduled workflow there, and then follow the same steps to configure variables, connector actions, expressions, conditions, and report processing. Generate Licensing Report returns the initial submission response without automatically polling; the flow manages subsequent polling explicitly.
| Step | Connector action |
|---|---|
| Submit | Generate Licensing Report |
| Poll | Get Licensing Report Operation Status |
| Download | Download Licensing Report File |
The flow polls the same operation in a Do until loop. After each poll, a condition checks whether status is Running. Only the branch for that status reads the poll response's Retry-After header and waits before the next iteration. A status of Succeeded or Failed exits the loop without another delay. The loop checks the response body and doesn't require the status endpoint to return HTTP 202.
If you're new to Power Automate, see Run flows on a schedule.
Step 1: Create the flow and variables
Sign in to Power Automate, and then select Create > Scheduled cloud flow.
Name the flow Weekly Copilot Credit report, set it to repeat every 1 Week on Monday, and then select Create.
Add three Initialize variable actions:
Name Type Value StartDateString formatDateTime(addDays(utcNow(),-14),'yyyy-MM-dd')EndDateString formatDateTime(addDays(utcNow(),-1),'yyyy-MM-dd')CreditThresholdFloat 1000Enter the date values as expressions. Together they request the previous 14 complete UTC days.
Step 2: Submit the report request and capture the operation
Add the Power Platform for Admins V2 > Generate Licensing Report action. When prompted, create a connection with the OAuth Connection authentication type, and sign in with an account that has one of the required roles.
Set the parameters:
Parameter Value Report Name FeatureDetailsPerResourceApi-version 2024-10-01startDate StartDatevariableendDate EndDatevariablegranularity Summaryformat jsonGenerate Licensing Report submits the request and returns
202 Acceptedwith the initialLocationandRetry-Afterheaders; it doesn't poll the operation.Confirm that the action's outputs contain the initial submission headers before continuing. If the action instead returns a later operation-status response without the operation URL, stop and check the connector version and response handling; the explicit polling steps require the initial
Location.After the submission action, add a Compose action named Report operation URL:
coalesce(outputs('Generate_Licensing_Report')?['headers']?['Location'],outputs('Generate_Licensing_Report')?['headers']?['location'])Add a Compose action named Report operation ID:
last(split(uriPath(outputs('Report_operation_URL')),'/'))This extracts the operation ID from the returned URL for the connector's Operation ID parameter. Keep the original URL for troubleshooting or resuming the operation; don't construct a new URL or submit a new report on every poll.
Add a Delay action named Initial report wait. Set Unit to Second and Count to:
int(coalesce(outputs('Generate_Licensing_Report')?['headers']?['Retry-After'],outputs('Generate_Licensing_Report')?['headers']?['retry-after']))The initial
Retry-Afterdefaults to300seconds (five minutes). Use the value returned by the service; it specifies when to poll, not how long generation takes. The API supplies a numeric interval in seconds. If the header is missing or malformed, investigate the response rather than substituting a zero-second delay.
Tip
If the run history shows a 429 status for Generate Licensing Report, don't resubmit immediately. If the response includes Retry-After, wait at least that many seconds before running the flow again.
Step 3: Poll, check the status, and wait only while running
After Initial report wait, add a Do until control. Set its left value to:
body('Feature_Poll_Status')?['status']Choose is not equal to, and enter
Runningon the right. The API's exact in-progress value isRunning, notInProgressorIn Progress. A Do until runs its actions before evaluating this exit condition.In the control's Parameters > Advanced parameters > Show all, set Count to
120and Timeout toPT2H. These limits prevent indefinite polling; they don't guarantee that report generation finishes within those limits.Inside Do until, add Power Platform for Admins V2 > Get Licensing Report Operation Status and rename it Feature Poll Status:
Parameter Value Report Name FeatureDetailsPerResourceOperation ID outputs('Report_operation_ID')Api-version 2024-10-01Immediately after Feature Poll Status, still inside the loop, add a Condition named Feature Wait If Running. Compare this expression with the text
Runningby using is equal to:body('Feature_Poll_Status')?['status']In the True branch, add a Delay named Feature Poll Delay. Set Unit to Second and Count to:
int(coalesce(outputs('Feature_Poll_Status')?['headers']?['Retry-After'],outputs('Feature_Poll_Status')?['headers']?['retry-after']))Read the header from the latest poll, not the initial submission: the recommended interval can change. If a
Runningresponse has no valid interval, stop and inspect the response rather than polling in a tight loop.Leave the False branch empty. Once the condition finishes, Do until checks the latest status:
Runningrepeats the poll after the delay; any other value exits to the terminal-status check.
The loop layout is Feature Poll Status > Feature Wait If Running > True: Feature Poll Delay / False: no actions, matching the same poll-check-wait logic used by the PowerShell REST example. HTTP 200 means the status request succeeded, not that the report is ready.
Step 4: Check the completed report status
After Do until, add a Condition outside the loop. Set the left value to this expression, choose is equal to, and set the right value to the expression
true:and(equals(body('Feature_Poll_Status')?['status'],'Succeeded'),not(empty(body('Feature_Poll_Status')?['fileName'])))Check the returned report status even if the action itself shows Succeeded. Continue only when generation succeeded and a file name is present.
In the False branch, add a Terminate action with Status = Failed. Set Message to this expression:
if(empty(body('Feature_Poll_Status')?['error']),concat('Report generation did not return Succeeded with a file name. Status: ',string(body('Feature_Poll_Status')?['status'])),string(body('Feature_Poll_Status')?['error']))A
Failedreport operation can't be resumed. This check also fails if the status is missing or unexpected, or if the status isSucceededbut no file name is present. If a loop limit is reached while the report is stillRunning, don't download the report or immediately submit another request. If submission, polling, or a delay fails, or if the loop times out, subsequent actions that require success are skipped. Inspect the run history and retain the operation URL before retrying or resuming.
Step 5: Download the report
In the True branch of the condition:
Add Power Platform for Admins V2 > Download Licensing Report File:
Parameter Value Report Name FeatureDetailsPerResourceFile Name body('Feature_Poll_Status')?['fileName']Api-version 2024-10-01Add a Parse JSON action, rename it Parse report JSON, and for Content, use:
body('Download_Licensing_Report_File')Use the following schema, which covers all 18 exported properties in report order.
ConsumptionDateis present forDailyreports and omitted forSummaryreports, so it isn't required. The root can be an empty array, but every returned row must contain numeric values forBilledCreditsandNonBilledCredits. Other string labels and IDs can be null or omitted.{ "type": "array", "items": { "type": "object", "required": [ "BilledCredits", "NonBilledCredits" ], "properties": { "ConsumptionDate": { "type": ["string", "null"] }, "BillingPlatform": { "type": ["string", "null"] }, "EnvironmentID": { "type": ["string", "null"] }, "EnvironmentName": { "type": ["string", "null"] }, "EnvironmentType": { "type": ["string", "null"] }, "ResourceID": { "type": ["string", "null"] }, "ResourceName": { "type": ["string", "null"] }, "ResourceType": { "type": ["string", "null"] }, "Product": { "type": ["string", "null"] }, "HarnessType": { "type": ["string", "null"] }, "ScenarioName": { "type": ["string", "null"] }, "Feature": { "type": ["string", "null"] }, "Channel": { "type": ["string", "null"] }, "KnowledgeSources": { "type": ["string", "null"] }, "ToolUsed": { "type": ["string", "null"] }, "LLMModel": { "type": ["string", "null"] }, "BilledCredits": { "type": "number" }, "NonBilledCredits": { "type": "number" } }, "additionalProperties": true } }Parse report JSON exposes every named property as dynamic content. Test with a report that contains rows to confirm that all exported properties are available and populated as expected. An empty array confirms only the array structure; it doesn't verify that row properties are present. To inspect the fields together, add a temporary Select action, set From to
body('Parse_report_JSON'), and map each named dynamic-content property. Remove the action after validation.In some connector runtimes, the downloaded body is a binary wrapper with
$content-typeand base64$content. In that case, change Content to:json(base64ToString(body('Download_Licensing_Report_File')?['$content']))The base64 value represents the HTTP payload after standard
Content-Encodinghandling; decoding it should produce plain JSON text. Base64 decoding doesn't decompress gzip data. If the decoded value is still gzip-compressed binary data or isn't valid JSON, stop the flow and inspect how the connector handles the response.
Step 6: Find rows over 1,000 credits and send a notification
Add a Select action, rename it Report rows, and set From to this expression:
body('Parse_report_JSON')Enter each value through the expression editor, not as literal text. In the new designer, enter
/in the value field and select Insert expression.Key Value Agentif(empty(item()?['ResourceName']),coalesce(item()?['ResourceID'],''),item()?['ResourceName'])Agent IDcoalesce(item()?['ResourceID'], '')Environmentif(empty(item()?['EnvironmentName']),coalesce(item()?['EnvironmentID'],''),item()?['EnvironmentName'])Featurecoalesce(item()?['Feature'], '')Total creditsadd(item()?['BilledCredits'], item()?['NonBilledCredits'])The
if(empty(...))expressions use the ID when a display name is null or an empty string. The schema requires both credit fields to be numbers. If either value is missing, null, or text, Parse report JSON fails instead of silently treating the value as zero.As an alternative to entering each value separately, select Switch to text mode in Report rows and paste this JSON object:
{ "Agent": "@if(empty(item()?['ResourceName']),coalesce(item()?['ResourceID'],''),item()?['ResourceName'])", "Agent ID": "@coalesce(item()?['ResourceID'],'')", "Environment": "@if(empty(item()?['EnvironmentName']),coalesce(item()?['EnvironmentID'],''),item()?['EnvironmentName'])", "Feature": "@coalesce(item()?['Feature'],'')", "Total credits": "@add(item()?['BilledCredits'],item()?['NonBilledCredits'])" }Enter each value as an
@expression, not an@{...}interpolated string or literal text. After a test run, inspect the Report rows output and confirm that Total credits is an unquoted number rather than a quoted string.Add a Filter array action, rename it High usage rows, and set From to the Output of Report rows. Select Edit in advanced mode, and enter:
@greater(item()?['Total credits'], variables('CreditThreshold'))Add a Condition that checks whether
length(body('High_usage_rows'))is greater than0. In the True branch, add Create HTML table (From = Output of High usage rows, labeled Body in some designers, or the expressionbody('High_usage_rows')), followed by Office 365 Outlook > Send an email (V2) with the HTML table in the body.Select Save, and then select Test > Manually to run the flow now.
If High usage rows is empty, the actions that create the HTML table and send the email are skipped. To test the True branch, temporarily lower CreditThreshold (for example, to 0) while using authorized test data, run the flow, and then restore the threshold to 1000.
Optional: Report billing details by environment
To use BillingDetailsPerEnvironment, keep the same flow and make these changes:
Set Report Name to
BillingDetailsPerEnvironmentin all three connector actions: Generate Licensing Report, Get Licensing Report Operation Status (named Feature Poll Status), and Download Licensing Report File. Keep the action names unchanged so the expressions still resolve.Replace the Parse report JSON schema with the following full 11-property schema.
BilledDateandAllocatedCapacityPackCreditsare present forDailyreports and omitted forSummaryreports. The two consumed-credit fields remain required numbers; string labels and IDs can be null or omitted.{ "type": "array", "items": { "type": "object", "required": [ "CapacityPackCreditsConsumed", "PayGoConsumedQuantity" ], "properties": { "BilledDate": { "type": ["string", "null"] }, "BillingPlatform": { "type": ["string", "null"] }, "TenantID": { "type": ["string", "null"] }, "EnvironmentID": { "type": ["string", "null"] }, "EnvironmentName": { "type": ["string", "null"] }, "EnvironmentType": { "type": ["string", "null"] }, "EntitlementID": { "type": ["string", "null"] }, "BillingPolicyId": { "type": ["string", "null"] }, "AllocatedCapacityPackCredits": { "type": "number" }, "CapacityPackCreditsConsumed": { "type": "number" }, "PayGoConsumedQuantity": { "type": "number" } }, "additionalProperties": true } }In Report rows, keep From as
body('Parse_report_JSON')and use this mapping:Key Value Environment IDcoalesce(item()?['EnvironmentID'], '')Environmentif(empty(item()?['EnvironmentName']),coalesce(item()?['EnvironmentID'],''),item()?['EnvironmentName'])Entitlement IDcoalesce(item()?['EntitlementID'], '')Billing policy IDcoalesce(item()?['BillingPolicyId'], '')Total creditsadd(item()?['CapacityPackCreditsConsumed'], item()?['PayGoConsumedQuantity'])
Keep the existing High usage rows filter expression, condition, HTML table, and email actions. The total combines capacity-pack and pay-as-you-go consumption for each returned environment billing row. These funding categories differ from the feature report's billed and nonbilled credit classifications. The flow doesn't aggregate all rows for an environment.
You can replace the email action with other business logic, such as posting to a Teams channel, creating a Dataverse row, or saving the report to SharePoint to maintain a long-term history.
Verify your results
- Confirm that the report file is a CSV with a header row or a JSON array. A header-only CSV or an empty JSON array (
[]) is a valid result when no qualifying consumption exists for the requested dates. - Compare a few values from report rows with the corresponding dimensions under Licensing > Copilot Studio in the Power Platform admin center. Small differences are expected for dates within the 30-day refresh window because late-arriving data and corrections can change the values.
FeatureDetailsPerResourceclassifies credits as billed and nonbilled.BillingDetailsPerEnvironmentinstead groups consumption by prepaid capacity and pay-as-you-go funding. These classifications don't necessarily map directly to one another. The reports can also use different date and processing bases, so their totals aren't guaranteed to reconcile. See Credit classification and interpretation.
Troubleshooting
| Problem | What to do |
|---|---|
400 Bad Request with InvalidRequestContent |
Check that endDate is on or after startDate, the dates use yyyy-MM-dd, and startDate is within the lookback (30 days by default). The error message names the earliest permitted date. |
401 Unauthorized |
Sign in again. For direct API calls, request a token for the https://api.powerplatform.com resource. If a submitted operation already exists, record and reuse its operation Location URL after renewing the token instead of submitting another report. |
403 Forbidden |
Sign in with a user account that has the Global Administrator, Power Platform Administrator, or Dynamics 365 Administrator role. Service principal connections aren't supported. |
404 Not Found |
Check the report name. For polling and downloads, use the Location URLs returned by the service unchanged. |
429 Too Many Requests |
If submission protection is enforced, wait for the interval specified by the service before submitting another report. REST and connector clients should honor Retry-After. The native CLI doesn't currently expose that header, so don't automatically retry using an assumed interval. Use the REST example when you need dynamic header handling. |
Operation status is Failed |
Stop polling that operation and submit a new request later. |
| Downloaded file looks like binary data | PowerShell 7 normally honors gzip Content-Encoding; don't manually decompress content that's already decoded. For a connector binary wrapper, base64-decode $content to text and parse the resulting JSON. If the decoded payload is still gzip-compressed data, stop and investigate how the client or connector handles the response rather than treating it as JSON. |
In Power Automate or Copilot Studio, the initial 202 response headers aren't available after Generate Licensing Report |
The submission action must return the initial Location and Retry-After without polling, with Asynchronous Pattern On (the default). Stop and check the connector version and response handling if these headers are absent. Don't extract an operation ID from a later status response, disable the setting, or switch designers. |
Feature Poll Status returns HTTP 200 with status: Running |
This is expected. Feature Wait If Running must read the latest Retry-After, delay for that many seconds, and let Do until poll again. Download only after the terminal check confirms Succeeded with a file name. |
A Running response has a missing or invalid Retry-After, or the polling loop reaches a limit |
Stop and inspect the run history. Don't substitute a zero-second delay, download an incomplete report, or submit another report in a tight loop. Retain the operation URL to resume polling the same operation after resolving the issue. |
In Power Automate, Parse report JSON receives $content-type and $content |
The connector returned a binary wrapper. Use json(base64ToString(body('Download_Licensing_Report_File')?['$content'])) as the Parse report JSON content. This decodes the wrapper; it doesn't decompress gzip data. |
| In Power Automate, Parse report JSON fails | Confirm the request used format=json, the connector version exposes JSON, and the root is an array. The schema deliberately fails when either required credit field is missing, null, or nonnumeric. Update the schema and mappings if you intentionally switch report types. |
| A descriptive value is empty | Optional labels can be empty or null, so the examples use resource or environment IDs where available. Required credit fields must be present and numeric; the examples stop rather than treating missing credit data as zero. |