User guide
How WattScope attributes what you record, how to read it back at project and at organization level, and what every tool on the connector does. For a shorter orientation, read the documentation page first.
1. The two surfaces
One account, two ways in. Both read and write the same rows.
| Surface | Where | What you do there |
|---|---|---|
| The connector | inside your AI client | record usage as you work, and ask for figures in plain language |
| The dashboard | this site | read the totals, export CSV, import a claude.ai data export |
To connect, add a custom connector in your client with this URL:
https://www.wattscope.com.au/mcp
There is no API key to paste and nothing to install — sign-in is a link sent to your email, or Google. Your first sign-in creates your account and a workspace to go with it. The step-by-step for each client covers the clicks.
2. What every record is attached to
Four attributions travel with every unit of usage. Knowing which is which is most of knowing how to read a report.
| Attribution | What it is | How it is set | How long it lasts |
|---|---|---|---|
| Organization | the workspace that owns the data | created for you at registration | permanent |
| Member | you, inside that workspace | your sign-in | permanent |
| Project | the piece of work usage counts toward | set_project | until you change it |
| Session | one stretch of tracked work | start_session | until you start another |
A session is not a conversation. It is a marker you move deliberately. If you never start one, everything keeps landing in the same session however many conversations have gone by. If you want a report that says this piece of work, start a session when that work starts.
The project persists. Setting it stays in force across conversations, restarts and days, until something changes it. Usage recorded before the change stays where it was — changing the project never rewrites history.
Both are held per person, per workspace. If you belong to two workspaces, each keeps its own active project and its own session, and switching back resumes rather than restarts.
Usage that arrives with no project named lands in a project called
unassigned. That is the default, not an error.
3. Tracking at project level
Your own usage, attributed to a name you choose. You do not call these tools yourself — you say what you want and your assistant chooses.
“Set my WattScope project to Reef survey.”
set_project — everything recorded from now on counts toward it, and the answer names the project you just moved away from.
“Start a new session for the reef survey, labelled ‘Tuesday field data’.”
start_session — the label is optional and appears in reports instead of the raw session id.
“Record that as 40,000 input and 8,000 output tokens on Sonnet.”
record_usage — one unit of usage, written against your workspace, session and project.
Give it whatever the underlying API response actually reported, including prompt-cache tokens. On agentic or multi-turn work those are routinely larger than plain input tokens, and leaving them out is the single most common reason a footprint reads low.
Recording the same work twice is easy to do and hard to notice, so record_usage takes an idempotency key — a handle for the piece of work. Record it again under the same key and the answer says replay: nothing is added, and the figures you get back are the ones already stored.
“What has the reef survey project cost in carbon? And since 1 August?”
get_project_footprint — your own usage against that project, across every session you have run.
“Which of my projects is using the most?”
list_projects — every project you have tracked, heaviest first, with an overall total.
“What has this session used?”
get_session_footprint — the current session only, yours only.
4. Tracking at organization level
An organization total is every member's usage, not just yours. One tool reads it, and it is admin-only: if your role in the active workspace is not admin, the call fails rather than quietly narrowing to your own rows and handing you a number that looks like the team's.
“Show me the whole organization's footprint for this month.”
org_footprint — the whole workspace, or one project across every member.
The same distinction runs through the dashboard. Signed in as an admin, the headline footprint and the By project table cover the whole organization; signed in as an ordinary member, both cover only your own usage. The CSV export follows whichever of the two you are, and says which in its header block.
If you belong to more than one workspace, your assistant will ask which one before it records anything — set_active_org switches between them, and each keeps its own project and session.
Several people in one workspace
Not yet. Everyone who registers gets a workspace of their own and is its admin; invitations are not enabled on this deployment, so a new sign-in starts a fresh workspace rather than joining an existing one.
The organization-level tools are real and correct — but today an organization total and your own total are usually the same number. If you need several people in one workspace, tell us.
5. Why a report shows two figures
Every figure carries a source grade — how the token counts were come by. The grades divide into two classes, and reports keep the classes apart instead of adding them up.
| Source | What it is | Billing-grade? |
|---|---|---|
| Vendor Admin API | Token counts pulled from the vendor's own usage API, reconcilable against the bill. The strongest provenance available. | Yes |
| Transcript sync | Token counts read from the conversation transcript the vendor returned. Machine-recorded, but not reconciled against a bill. | No |
| Client-measured (OTLP) | Token counts exported by the AI client's own instrumentation as the work happened. Machine-recorded, and trusted as far as the client is. | No |
| Self-reported | Token counts entered by hand, by a person or by an assistant acting for one. Unverified: nothing checks them against the vendor. | No |
How to read a footprint your assistant reports back:
- Billing-grade is reconciled against a vendor invoice. It is the only portion defensible in a disclosure or a report to a third party.
- Indicative is reconciled against nothing.
- Combined adds the two together. It may be quoted, but never without saying that it spans both classes.
- Where a class is empty, the honest line is “no billing-grade usage on record” — not “0 g”, which reads as a measurement of zero.
No billing-grade path exists yet
The connection to a vendor's usage API is not built, so everything you can currently record is indicative. That is a real limit on what these numbers can be used for, and it is why the distinction is drawn on every surface rather than hidden.
6. Every tool
Your client lists these under its own titles. The names below are what your assistant calls, and are worth knowing for one reason: when a figure looks wrong, naming the tool is the fastest way to say what you actually want. Required arguments are shown in black.
Recording
Records one unit of usage against your workspace, session and project, as
self-reported. project overrides the active
project for this one record without changing it for later calls. Returns
the event's own footprint plus the running session footprint, split by
grade.
For Claude Desktop, where no token counts exist anywhere — the client publishes none and your assistant cannot see its own usage. It sends character counts per turn instead, which are observations rather than guesses, and the conversion happens here against one documented constant so it can be audited and corrected later.
The whole conversation is sent each time under a stable handle, so turns already stored replay instead of counting twice. The handle is hashed before anything is written: the rows carry a digest, never the words. What comes back is a span — a floor, a calibrated figure and a ceiling — and every one of the three is itself a floor, because system prompts, tool schemas, thinking tokens and attachments are invisible to this method. Real usage was higher, never lower.
Organizing what gets recorded
Sets the project subsequent usage counts toward. Persists until changed.
Starts a new session, replacing the current one, and can move the project at the same time.
Switches which workspace subsequent calls operate on. Only needed if you belong to more than one.
Reading
This session, your usage. Says so in words when no session has been started here, rather than printing a zero that reads as a measurement.
One project, your usage, across every session. Defaults to the active project. since is a date or timestamp — a value it cannot read raises rather than quietly returning zero.
Every project you have tracked, heaviest first, with an overall total. Each row says which grades produced it.
The whole workspace — every member, not just you. scope is the whole organization or one project across every member.
Everything else
Which workspace, session and project you are currently recording against, the factor set in use, the region, and what each grade means. Returns no footprint figures. The first thing to ask for when a number looks wrong.
What it would cost to offset a recorded footprint. Offset purchasing is not available in this version — it reports the quantity that would need retiring and says so; it never starts a transaction. Naming a quantity yourself prices a number nothing here measured, and the answer says that too rather than lending it provenance it never had.
7. The two prompts
Prompts are yours to pick, from your client's prompt or slash-command menu — as opposed to tools, which your assistant chooses. Use them when you want the thing done without having to phrase it.
Record this conversation's footprint so far. Recorded as self-reported, which counts as indicative.
A written report for this session, the active project, or everything you have tracked — with the two classes reported separately and the caveats reproduced in full.
8. Usage that arrives without the connector
Import a claude.ai data export
Request your export from claude.ai, then upload the archive it sends you on
the import page — exactly as it
downloaded, not unzipped and not renamed, up to
16 MB. WattScope reads token counts out of the
conversations.json inside it and records them as transcript
sync.
Nothing automated can fetch an export for you: the download links authenticate by your claude.ai session, so a signed-in human has to do it. The file is read in memory to count what it contains, is never written to disk, and is discarded once the counts are stored.
Imported usage lands in unassigned, because a transcript carries
no project and inventing an attribution would be worse than not having one.
Send telemetry from an instrumented client
Claude Code can export its own OTLP logs straight to this service, recorded as client-measured. That needs a token issued for your organization and there is no self-serve page for it yet, so ask us if you want one.
Two things to know. That telemetry carries end-user email addresses in plain
text, and they are replaced with a keyed per-organization digest at the edge
— the address itself is never stored, and the same address in two
organizations produces two unrelated values. And these rows also land in
unassigned until per-project attribution is built.
9. Limits, and what happens when you hit one
| Limit | On this deployment |
|---|---|
| Events per organization, rolling 24 hours | 50,000 |
| Events per organization, total | no ceiling |
The daily ceiling is a rolling 24-hour window, not a calendar day, so it recovers gradually as old events age out rather than returning a whole allowance at midnight in a timezone we would have had to pick for you.
A write that meets a ceiling is refused, not queued, and every path says so in its own answer rather than reporting a quiet success. Usage you tried to record is not stored and will not appear later — so if your assistant tells you an account is full, the figures for that work are missing from the total, not delayed.
10. Getting your data out
The dashboard exports a CSV of usage by project. It opens with a comment block — the organization, whether the figures are org-wide or yours, the split by class, the factor set version, the export timestamp and the disclaimer — and then one row per project:
project, sources, mixes_billing_and_indicative, events, co2e_grams, energy_wh, first_seen, last_seen
A spreadsheet does not look like an estimate, so the file says what it is.
Readers that skip # lines get a clean rectangle.
You can export at any time without asking us. To have data deleted, write to us from the address on the account; the Privacy Policy says exactly what goes with it.
11. When something looks wrong
| What you see | Usually |
|---|---|
| A report shows nothing | No session has been started in this workspace yet. An absence of records is not a measured zero, and the answer distinguishes them. |
| Usage went to the wrong project | The active project persists across conversations. Ask for server_info to see what is actually active. |
| A footprint reads low | Prompt-cache tokens were left out. They frequently dwarf plain input tokens. |
| The same work was counted twice | No idempotency key was passed. With one, a repeat replays instead of adding. |
| You are asked which organization | You belong to more than one, and nothing has been picked yet. |
| The org-wide report refuses | Your role in the active workspace is not admin. |
Anything else: support and security contact. If a figure looks wrong, tell us what you expected and when you recorded it — the factor set version on the response is what lets us reproduce it.
12. What these figures are, and are not
These are estimates, not measurements. Providers do not publish per-token energy figures for hosted models, so the per-model values are inferred from public analyses of whole-query energy use and are uncertain by a factor of several in either direction.
This deployment runs factor set 2026.08.18a-draft, whose
status reads INDICATIVE - order-of-magnitude estimates, not measurements. Suitable for internal awareness and relative comparison; not for regulatory reporting, public claims, or offset retirement volumes.. The same string is returned to
every client that asks, so this page cannot claim more than the service does.
Two consequences worth carrying:
- Every stored event keeps the version of the factor table that produced it, so revising the table never silently rewrites your history.
- Grid intensity comes from this deployment's configured region, which is
global— an average, not your data centre.
Everything here is scoped to your organization: no tool call and no customer-facing page can read across that boundary, and the test suite treats that as a measured property rather than an assumption. The Privacy Policy states what WattScope Pty Ltd itself can see and the limits on why it looks; the Terms say what these figures may be used for.