Edit

Tutorial: Download Copilot Credit usage reports programmatically (preview)

[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:

  1. Submit a report request. The service returns 202 Accepted with a Location header (the operation-status URL) and a Retry-After header.
  2. Poll the operation until its status is Succeeded or Failed. Follow the polling interval specified by Retry-After. The status API returns 200 OK even while generation is in progress (status: Running), so check the response body rather than treating HTTP 200 as confirmation that the report is ready.
  3. Download the generated file, and then iterate through the rows. The REST example follows the operation response's Location URL; the connector and CLI examples pass the returned fileName to 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-After with a 429 response, 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

  1. Sign in to Power Automate, and then select Create > Scheduled cloud flow.

  2. Name the flow Weekly Copilot Credit report, set it to repeat every 1 Week on Monday, and then select Create.

  3. Add three Initialize variable actions:

    Name Type Value
    StartDate String formatDateTime(addDays(utcNow(),-14),'yyyy-MM-dd')
    EndDate String formatDateTime(addDays(utcNow(),-1),'yyyy-MM-dd')
    CreditThreshold Float 1000

    Enter the date values as expressions. Together they request the previous 14 complete UTC days.

Step 2: Submit the report request and capture the operation

  1. 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.

  2. Set the parameters:

    Parameter Value
    Report Name FeatureDetailsPerResource
    Api-version 2024-10-01
    startDate StartDate variable
    endDate EndDate variable
    granularity Summary
    format json
  3. Generate Licensing Report submits the request and returns 202 Accepted with the initial Location and Retry-After headers; 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.

  4. 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'])
    
  5. 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.

  6. 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-After defaults to 300 seconds (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

  1. 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 Running on the right. The API's exact in-progress value is Running, not InProgress or In Progress. A Do until runs its actions before evaluating this exit condition.

  2. In the control's Parameters > Advanced parameters > Show all, set Count to 120 and Timeout to PT2H. These limits prevent indefinite polling; they don't guarantee that report generation finishes within those limits.

  3. Inside Do until, add Power Platform for Admins V2 > Get Licensing Report Operation Status and rename it Feature Poll Status:

    Parameter Value
    Report Name FeatureDetailsPerResource
    Operation ID outputs('Report_operation_ID')
    Api-version 2024-10-01
  4. Immediately after Feature Poll Status, still inside the loop, add a Condition named Feature Wait If Running. Compare this expression with the text Running by using is equal to:

    body('Feature_Poll_Status')?['status']
    
  5. 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 Running response has no valid interval, stop and inspect the response rather than polling in a tight loop.

  6. Leave the False branch empty. Once the condition finishes, Do until checks the latest status: Running repeats 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

  1. 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.

  2. 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 Failed report operation can't be resumed. This check also fails if the status is missing or unexpected, or if the status is Succeeded but no file name is present. If a loop limit is reached while the report is still Running, 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:

  1. Add Power Platform for Admins V2 > Download Licensing Report File:

    Parameter Value
    Report Name FeatureDetailsPerResource
    File Name body('Feature_Poll_Status')?['fileName']
    Api-version 2024-10-01
  2. Add 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. ConsumptionDate is present for Daily reports and omitted for Summary reports, so it isn't required. The root can be an empty array, but every returned row must contain numeric values for BilledCredits and NonBilledCredits. 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-type and 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-Encoding handling; 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

  1. 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
    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'])

    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.

  2. 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'))
    
  3. Add a Condition that checks whether length(body('High_usage_rows')) is greater than 0. In the True branch, add Create HTML table (From = Output of High usage rows, labeled Body in some designers, or the expression body('High_usage_rows')), followed by Office 365 Outlook > Send an email (V2) with the HTML table in the body.

  4. 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:

  1. Set Report Name to BillingDetailsPerEnvironment in 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.

  2. Replace the Parse report JSON schema with the following full 11-property schema. BilledDate and AllocatedCapacityPackCredits are present for Daily reports and omitted for Summary reports. 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
      }
    }
    
  3. In Report rows, keep From as body('Parse_report_JSON') and use this mapping:

    Key Value
    Environment ID coalesce(item()?['EnvironmentID'], '')
    Environment if(empty(item()?['EnvironmentName']),coalesce(item()?['EnvironmentID'],''),item()?['EnvironmentName'])
    Entitlement ID coalesce(item()?['EntitlementID'], '')
    Billing policy ID coalesce(item()?['BillingPolicyId'], '')
    Total credits add(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

  1. 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.
  2. 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.
  3. FeatureDetailsPerResource classifies credits as billed and nonbilled. BillingDetailsPerEnvironment instead 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.