Copilot Spend

Web Portal → Copilot spend

Available since Stable 1857 (PR #787).

Copilot spend answers one question: who consumed Copilot credits, when, from which source, and where in the organisation? It reports facts as the two sources state them and applies no prices, no value and no recommendations. To weigh what Copilot costs against what the evidence of use supports, use Copilot investment, which reads the same sources. For how these figures relate to the other Copilot cost and value figures, see the cost and value map.

Where	Insights → Copilot → Copilot spend (#/insights/copilot-spend), directly after Copilot investment
Periods	Last 7, 28 or 90 days
Who can open it	Any signed-in reader. Anything that names a person needs See PII: the People tab, a person's detail, a user filter and the Direct manager grouping. See Portal Permissions
Filters	The administrator's global report filter narrows every figure, as on every Insights report. A reader with See PII can add their own user filter on top. Either one makes it a filtered view
Needs	At least one of the two sources below. The page itself needs no saved assumptions and no Storage connection string
Output	Excel report and Print buttons on the page

On this page

1. The two sources, kept apart
2. Connection warnings
3. Overview
4. Copilot Studio billed usage
5. Copilot credits consumed (readings)
6. Organisation
7. People and person detail
8. What the page withholds
9. Excel report
10. When a panel is empty
11. Try it with the Contoso demo
12. Limitations

The two sources, kept apart

The page draws on two sources that can describe the same consumption in different ways. It lays them side by side and never adds them together.

	Copilot Studio billed usage	Copilot credits consumed (readings)
Badge on the page	Billed, by day	Latest reading, not a bill
What it is	A daily ledger of credits billed for Copilot Studio agents, filled by the agent cost import	Each person's latest reading of credits consumed, collected by the preview Copilot credit history connection
Does it add up over the period?	Yes. It is a daily ledger	No. A reading is what the source says a person had consumed as of a date, in an accounting period the source does not identify. Readings are never summed across days, and an absent value is never read as zero
Switched on by	CopilotStudioCredits=True in ImportJobSettings, and ledger rows (Agent Costs Import Configuration)	CopilotCostManagement=True in ImportJobSettings and the app setting CopilotCostConnectionEnabled = true. With either off, readings already collected are labelled as retained history

A banner at the top of the page says the same thing in one sentence: Copilot Studio billed usage is a daily ledger, so it adds up over the period. Copilot credits consumed come from each person's latest reading on a date, in a period the source does not identify, so they are never added to it or summed across days.

Connection warnings

Under the filter bar, this page and Copilot investment check the two cost connections once a minute (api/CopilotCostHealth, open to any signed-in reader) and warn when one needs attention. Nothing shows while a source is healthy, switched off, or has no connection saved: a source nobody connected is a choice, not a fault.

Banner text	What the check found
An administrator connection is saved, but no successful cost API read has been recorded. (an information bar, not a warning)	Pending: a connection exists, but nothing has been read yet
The delegated cost connection needs renewal. Reconnect in Administration.	Reconnect required
Cost API access was refused. Check the delegated account's permissions in Administration.	Permission denied
Cost API collection is failing; recent cost data may be incomplete. Check Administration.	Failing
Cost connection health could not be read. Check Azure Table storage access.	Unavailable: the connection store could not be read

Each warning is headed Copilot Credits collection needs attention (the preview credit history connection) or Copilot Studio consumption needs attention (the billing connection). It also says Last successful API read: {when}. Previously collected figures remain available. (never when there has not been one) and a recovery note:

• Credits: Collection retries automatically. Missed daily balance snapshots cannot be recreated as historical spend.
• Studio: After recovery, Studio re-reads the configured look-back window. Older dates need a larger window and must still be retained by the API.

An administrator gets a Check billing connection link to Administration → Copilot credit history (preview) or Administration → Copilot Studio billing connection. Every other reader sees Ask a portal administrator to check the saved billing connection. If the health check itself fails, the page says Cost connection health is unavailable. Do not assume the saved connections are working. The server gives up after 15 seconds and answers unavailable for both sources; it keeps an answer for 30 seconds.

The same checks feed the Health page, as the components Copilot Credits API and Copilot Studio consumption API, and the installer-managed alert rules: see Health Alerts.

Overview

The first tab puts the two sources next to each other without combining them:

• Credits billed in the period. The ledger total, the number of people with billed usage, and a note when some credits were not matched to a person by the user import.
• Consumed credits (latest reading). The sum of each person's latest reading, the date it was read, how many people have consumed credits (of the number read), and "N with an amount the source did not state and M partial readings: unknown, not zero." Accounts the user import did not match to a person are included in the total and called out separately. Unmatched accounts, and Studio credits the user import did not match to a person, are counted only for the whole tenant, so a filtered view does not show them.
• Where it is consumed. The groups with the most credits by the grouping you chose (billed Studio credits, or consumed credits at the latest reading), with a link to every group.
• Readings trend. Each point is a reading as of its date; the points are never added together.
• What the credits went on. Three lists, each one source's own breakdown with shares of its own total: billed Copilot Studio credits by environment, billed credits by agent (agent ledger), and consumed credits by category (latest reading). They come from different sources, so they are never added together. Links open the two source tabs.

Copilot Studio billed usage

Credits billed for Copilot Studio agents, day by day, from the imported ledger. These add up over the period.

Facts shown: people with billed usage; how many of those credits were not matched to a person; the date the ledger starts; the latest day in the ledger; and when the last import ran.

Billed credits by day is a line chart. A day with no charges is drawn at zero. A day after the ledger's latest stored day is hatched with diagonal stripes ("not in the ledger yet") and breaks the line, so a day that has not been imported yet is never drawn as zero.

By environment lists billed credits per Power Platform environment in the period for the people in this view. Microsoft reports each person's usage by environment, not by agent, so the rows add up to the total above. For a reader without See PII, an environment small enough to stand for one person is combined with the other small ones into an Other environments (N) row, and a combined row that is itself too small shows how many people it holds but no credits, so the rows add up to the total only apart from that row.

By agent (tenant agent ledger) is recorded per agent, not per person, so it can differ from the per-person total and is never added to it. It cannot be narrowed to the people in a view, so it is shown unfiltered only (Not shown in a filtered view).

Copilot credits consumed (readings)

Each person's latest consumed credits, from the preview collector. The title carries (preview) because the source is a Microsoft Graph beta API. The accounting period is shown as Not confirmed by the source unless the readings carry a confirmed month. Read What the figures mean before quoting a number from this tab: consumedQuantity is documented as UTC month-to-date credits, so a reading is never a day's spend.

Facts shown:

Fact	Meaning
Consumed credits (latest reading)	The sum of each person's latest reading
Read on	The date of the readings used
Accounting period	Not confirmed by the source today. The page can also show Confirmed by the source or Confirmed for some readings only when readings carry a confirmed accounting month
Source last changed the readings	The range, oldest to newest, of when the source last changed the readings used
Collection sweeps in the period	N started, M completed
People with a reading / with consumption above zero	How many were read, and how many consumed anything
Partial readings	A reading where the source could not evaluate every category
Amounts the source did not state	Unknown, not zero
Categories in another unit (left out of the totals)	Units other than credits are never added to credits
At a credit limit / Not entitled	People whose reading says a limit is reached, or that they are not entitled
Accounts not matched to a person	Directory accounts the user import did not pick up; their credits are counted in the total

Consumed credits on each reading date is a trend with one point per reading date. Readings on different dates can count the same consumption again, so they are never added together. By category lists consumed credits at the latest reading by category and unit, as the source reports them. A category the source could not evaluate, or whose amount it did not state, is counted, not read as zero. Spending policies and tenant pool balances describe the whole tenant, so a filtered view does not show them.

Organisation

Billed Studio credits and consumed credits by group, side by side and never added. Group by offers Department (the default), Company, Country or region, Job title, Office location, Email domain and Usage location. A reader with See PII can also group by Manager or by a custom directory attribute the tenant holds.

Column	Meaning
People	People in the group
Studio credits (period)	Billed Copilot Studio credits in the period
Share of Studio	The group's share of the billed total
Consumed credits (latest reading)	The group's latest readings
Share of consumed credits	The group's share of the consumed total
Unknown amounts	People in the group whose amount the source did not state

Small groups. The minimum group size is 5, fixed: unlike Copilot investment, this page does not follow a larger minimum set in Copilot Adoption settings. Groups with fewer than 5 people are combined into one row, Other small groups (N). If the combined row is itself under 5 people it shows its head count but no amounts (Fewer than 5 people: figures not shown), so no amount is shown for fewer than 5 people.

Manager grouping. Grouping by manager names people, so it needs See PII: the option is not offered without it, and the server refuses the request if it is asked for anyway (This grouping names people, which needs the See PII permission). Because it is only for readers who may see individuals, it lists every group, whatever its size.

The page shows the top 100 groups plus "N more groups (each listed in the Excel report)". A group with no value for the attribute is shown as Not set. If the directory cannot be read (The people cannot be grouped right now: the user directory could not be read.), or the attribute you chose is no longer held (the directory no longer holds it. Choose another grouping.), the panel says so; the totals elsewhere on the page are unaffected.

How consumption is spread across people

Below the groups, one source at a time (Studio billed credits or consumed credits):

• Statistics: median per person, average per person, 90th percentile, the share consumed by the top 10 % and top 20 % of people, concentration (Gini coefficient), people with a reading of zero, the lowest per person (above zero) and the highest per person.
• Bands ("from … to under …"), a Pareto curve, and the largest consumers and smallest consumers above zero.
• With fewer than 5 consumers the spread is not shown.
• Without See PII the spread is anonymised: each band covers at least 5 people and no single person's amount is shown.

People and person detail

The People tab needs See PII. It lists people with a search box (Name, department, job title or manager), a source filter (Either source / Billed Studio usage / Credits consumed (readings)) and sorting.

Columns: Person, Department, Manager, Studio credits (period), Days billed, Consumed credits (latest reading), Read on, Notes. Notes carry the flags Partial reading, Amount not stated, Other unit, At credit limit and Not entitled.

Selecting a person opens their detail (api/CopilotSpend/person/{id}, See PII, limited to the current scope; a person outside the current view returns This person is not in the current view):

• Rank — Ranked N of M people, X % of the total.
• Billed Studio credits by day and by environment.
• Consumed credits by category, and the readings history — each reading is the credits consumed as of that date, not a day's spend — with a marker for readings at the credit limit.
• What they used Copilot for, from the Copilot audit log and interaction history for the same period. It shows counts, apps, agents, goals and key phrases only. The text of prompts and responses is never stored, so it is never shown.
  • Interactions by day (all, and with agents) and by kind: Copilot without an agent, With an agent, Cowork, Testing agents in Copilot Studio.
  • Interactions by app.
  • Agents used: kind (declarative, custom engine or not recorded), who built it, interactions, interactions in the test pane, estimated credits and last used.
  • Prompts: days with prompts, average words, files, links, @mentions, context items, and the first and latest prompt; prompts by goal and by app.
  • Key phrases, which need the interaction-history import with cognitive enrichment (Copilot reports and prompt history).
  • Most recent prompts (metadata only) and what Copilot referenced.
  • The importer's credit estimate is not a bill and is never added to billed or consumed credits.
  • A part that cannot be read says Not available and means unknown, not none.

What the page withholds

What is held back	When
Whole-tenant figures: spending policies, pool balances, the by-agent ledger, and the count of accounts or Studio credits the user import did not match to a person	Any filtered view, whether from the administrator's global filter or a reader's own. A banner says Filtered view: figures that describe the whole tenant are withheld.
A group's figures	The group has fewer than 5 people (see Organisation)
An environment's figures	The reader lacks See PII and the environment is small: Other environments (N) or Too few people to show figures
Individual amounts in the spread	The reader lacks See PII (bands of at least 5 people; fewer than 5 consumers shows no spread)
The People tab, person detail, a user filter, the manager grouping	The reader lacks See PII. The server answers 403 rather than an emptied result, and the page hides what the server would refuse
Since Stable 1859 (PR #807): one source's figures for a group, section totals, ledger days, trend points and balance categories that describe one to four people, plus further groups or days that would reveal them by subtraction	The reader lacks See PII
Since Stable build 1860 (PR #866): credits held by one to four accounts that the user import didn't match to a person, together with the balances total. They show as withheld, never as 0	The reader lacks See PII (details)

Endpoint	Who may call it
api/CopilotSpend/summary, trend, export/workbook	Any signed-in reader. A user filter or manager grouping needs See PII, and the workbook leaves the people sheets out without it
api/CopilotSpend/people, person/{id}	See PII

Excel report

Excel report downloads copilot-spend-{date}-{days}d.xlsx for the period and filter on screen, in the language the portal is set to. No prices are applied. Sheets, in order: Summary, Organisation, Copilot Studio billed usage, Copilot credits consumed, Distribution and — only with See PII — Top spenders, Lowest spenders and People. The Summary sheet states Per-person data: Included or Not included (needs the See PII permission). An export is never less redacted than the screen.

When a panel is empty

Each message below is the page's own wording.

Message	What it means	What to do
The Copilot Studio credit import is turned off, so there is no billed usage to show.	CopilotStudioCredits is not enabled	Turn the import on: Agent Costs Import Configuration
No billed Copilot Studio usage has been imported yet.	The import is on but the ledger has no rows	Wait for an import cycle; check the import status on Agent costs
The Copilot Studio ledger could not be read just now.	The ledger query failed	Try again; check SQL health. The figures are missing, not zero
The breakdown by day, environment and agent could not be read just now.	The totals loaded but the breakdown did not	Try again; check SQL health
…so recent days may be missing.	The latest Studio import reported an error	Check the importer log
…the days before it have no data, which is not the same as zero.	The ledger starts after the period begins	Nothing to fix: read the figures from the ledger's start date. Earlier days are unknown, not zero
Collection of Copilot credits consumed is turned off: this is the history already collected.	CopilotCostManagement or CopilotCostConnectionEnabled is off	Turn collection on only after the connection is set up
The newest reading is from {date}, before the selected period starts… The collector may have stopped.	No sweep has landed in the period	Check the credit history connection and the importer
The database has not been upgraded for Copilot credits consumed yet.	The preview collector tables are missing	Upgrade the database to the build you are running
There is no reading of Copilot credits consumed in this period.	The collector is on but nothing was read	Check the connection status
Copilot credits consumed could not be read just now.	The readings query failed	Try again; check SQL health

Errors loading the page itself read The Copilot spend report could not be loaded ({status})., The consumption readings could not be loaded, The people could not be loaded and This person's consumption could not be loaded.

HTTP 404.15 (query string too long) when a filter is applied comes from IIS, not from the page. The website was deployed without its generated Web.config, which allows this API longer query strings. Redeploy the whole Website.zip: see Manual install: deploy the binaries.

Try it with the Contoso demo

Every panel can be filled with synthetic data, without a real tenant:

Tests.FakeDataGen.exe demo --database ContosoDemo_Example

• The command creates a new LocalDB-only database ((localdb)\MSSQLLocalDB), applies the schema, and refuses any other server or an unmarked or changed target. It never reads a configured production connection. An exact, completed rerun is a read-only no-op; use a new name after a failure.
• The copilot-credits area writes the preview credit-balance history (daily sweeps for up to 92 days, per-service balances that reset monthly, policies, tenant balances, and deliberate gaps: absent, throttled and partial sweeps). copilot-history writes prompt and response metadata. Add --areas to generate only some areas.
• Since format contoso-demo-v6 the interaction history is persona-driven, so a person's What they used Copilot for has something to show. A database generated in v5 or earlier has none of that: generate a new one under a new name.
• The run prints the ImportJobSettings and CopilotCostConnectionEnabled values the web application needs. The portal decides what it can measure from those settings, not from the rows in the database. Never connect a real Graph reader to a demo web application.
• Credit rates, policies and pools are illustrative values, not Microsoft's prices or catalogue. Balances are point-in-time readings with an unverified accounting period, exactly as the live collector stores them.

The generator's own documentation is the Tests.FakeDataGen README.

Limitations

• Per-user Studio figures are by environment, not by agent. Microsoft reports usage by environment; the per-agent ledger is a separate, tenant-level list.
• Consumed credits are each person's latest reading only. The page cannot turn successive readings into a daily bill, and the workbook has no readings curve.
• Preview accounting periods are unverified, and the source is a beta Microsoft Graph API whose contract may change.
• Prompt detail is metadata. The product stores counts, apps, agents, goals and key phrases, never the text of a prompt or response.
• Very large tenants. At 200,000 users an unscoped, long-window credit trend still reads about 2 GB of service rows (the result is cached afterwards). On the pull request's synthetic tenant the same 90-day trend scoped to 20,000 people took about a fifth of the page reads and about a quarter of the time, so a filter that narrows the people helps on a tenant that size. Those timings are from LocalDB on one machine; Azure SQL was not measured.
• Credit estimates are not bills. The importer's per-turn estimate is an approximation and is never added to billed or consumed credits.

---

Return to Web Portal · Copilot investment · Copilot credit history (preview) · Agent costs