[DOCS] Clarify what query_source="auxiliary" covers on cost.usage / token.usage metrics

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/monitoring-usage

Section/Topic

Cost counter / Token counter — the query_source attribute (and its differing definition under API request event)

Current Documentation

Under Cost counter and Token counter, query_source is documented as a closed enum:

query_source: Category of the subsystem that issued the request. One of "main", "subagent", or "auxiliary"

Under API request event, the same attribute name is documented as free-form instead:

query_source: Subsystem that issued the request, such as "repl_main_thread", "compact", or a subagent name

And the Monitoring page already instructs operators to filter on it:

Filter the token or cost side to rows where query_source is "main" so auxiliary and subagent requests don't attribute the session's commits to a model that didn't make them.

What's Wrong or Missing?

auxiliary is listed as an enum value but never defined anywhere in the docs. Since query_source is the attribute organizations use to attribute spend, and the docs actively tell operators to filter to main, following that guidance means silently discarding a slice whose contents are undocumented — with no way to know whether it is negligible overhead or a material cost centre.

Two related gaps:

1. The events stream and the metrics stream document the same attribute name differently — raw subsystem strings on api_request events versus three bucketed categories on the metric counters — and the mapping between them isn't published. "compact" is the only concrete example given of anything that is neither the main thread nor a named subagent, which suggests but does not confirm that it lands in auxiliary.
2. query_source is sometimes absent entirely, which the closed-enum framing doesn't allow for (more below).

What we measure

I run a self-hosted OTel collector for an enterprise deployment (~330 licensed users) landing in Athena, so I can characterise the bucket even though I can't identify it. Figures below are 14 consecutive days, all users, from claude_code.cost.usage and claude_code.token.usage. Percentages only — the absolute cost is Claude Code's client-side estimate against a seat-capped plan, so it reconciles to no invoice and only the ratios are meaningful.

Cost and request share (rel. cost/req normalised to main = 1.00):

| query_source | % of cost | % of requests | rel. cost/req |
|---|---|---|---|
| main | 81.9% | 72.3% | 1.00x |
| subagent | 11.4% | 10.5% | 0.96x |
| auxiliary | 6.0% | 16.6% | 0.32x |
| (attribute absent) | 0.7% | 0.6% | 1.12x |

auxiliary is a much larger share of request volume than of cost, so any dashboard that measures query_source by request or datapoint count rather than by cost will overstate it substantially. It reached 317 of 331 users, so it is not one feature's footprint.

Token share by type — this is the part that looks diagnostic:

| token_type | main | subagent | auxiliary |
|---|---|---|---|
| input (uncached) | 12.6% | 8.0% | 79.2% |
| output | 75.2% | 22.5% | 1.8% |
| cacheRead | 83.6% | 9.0% | 6.9% |
| cacheCreation | 73.2% | 19.3% | 6.9% |

auxiliary accounts for roughly four fifths of all uncached input tokens and almost none of the output: large fresh prompts in, very little generated out, largely bypassing the prompt cache. main is the mirror image — tiny raw input, dominant cacheRead — as expected for a cache-riding main thread. The auxiliary profile is what compaction, summarization, title generation, or classification helpers would look like, but distinguishing between those from telemetry alone isn't possible, which is why I'm asking.

Model routing: every frontier model sits at 4–7% auxiliary, but one label is dominated by it — claude-haiku-4-5-20251001 is ~76% auxiliary. So the model label already acts as a partial, undocumented breakdown of the bucket.

Stability: the daily auxiliary cost share held a 3–7% band across all six weeks of history I have, drifting from ~4% to ~6%, and reads consistently lower on weekends. Bucketing users into quintiles by cost-per-session gives 4.5% / 4.2% / 4.8% / 7.6% / 6.5% — rising with session intensity, but weakly and not monotonically. If compaction dominated the bucket I'd expect a much stronger relationship, which is part of why I suspect it's heterogeneous.

For what it's worth, ~6% closely matches the 6–7% of Opus spend visible in #63536. Two independent deployments landing in the same range suggests a structural share rather than a local quirk, and therefore something worth a sentence of documentation.

Questions

1. What does auxiliary include? Is it "every request Claude Code issues on its own behalf rather than in response to a user turn" — compaction/summarization, title generation, classification helpers, background precompute — or something narrower?
2. How do the raw query_source strings on api_request events map to the three metric categories? A mapping table (e.g. repl_main_thread → main, compact → auxiliary) would let operators reconcile the two streams. Confirming that the raw-string set is open-ended while the metric enum is closed would also help.
3. Is the enum stable? Public data in #59942 shows auxiliary absent from that org's cost.usage datapoints before 2026-05-10 and present after, implying it was added at some point. (My own history is too short to date the change independently — all three values are present from my first day of collection.) Are further additions expected, and would they be noted in the changelog?
4. Is auxiliary spend attributable further? agent.name / skill.name / plugin.name are documented for subagent and skill attribution. Is there an equivalent for auxiliary work, or is the bucket intentionally opaque? The Haiku concentration above suggests some of it is separable by model today; worth documenting if that's a stable property rather than an implementation detail.
5. What does an absent query_source mean? The metric attribute is presented as a closed three-value enum, but I see datapoints carrying no query_source at all — 0.7% of cost in the window above, spiking to 36% of a single day's cost on one day, and 100% of cost on the claude-opus-4-6[1m] and claude-sonnet-4-5 labels. It has since fallen to near zero, which makes it look like a client-version artifact, possibly the same root cause as #59942. Should operators treat absence as a fourth bucket, fold it into main, or exclude it?

Suggested Improvement

Three small additions to the Monitoring page:

1. Define each enum value under Cost counter, e.g.:

> query_source: Category of the subsystem that issued the request.
> - main — requests issued by the main conversation thread in response to a user turn.
> - subagent — requests issued by a subagent (see agent.name for which one).
> - auxiliary — requests Claude Code issues on its own behalf rather than in response to a user turn, such as conversation compaction, summarization, and title generation. Typically a small single-digit percentage of total cost.

(Adjust the specifics to match reality — the point is that operators need to know what falls in the bucket and roughly what magnitude to expect.)

1. Add a mapping note explaining the relationship between the free-form query_source on api_request events and the bucketed query_source on the metric counters, ideally as a short table.

1. State whether the attribute is guaranteed present on cost/token datapoints, and if it can be absent, say how operators should treat those rows.

Impact

Medium - Makes feature difficult to understand

Additional Context

Methodology, in case it matters for reading the numbers:

• Source is claude_code.cost.usage / claude_code.token.usage datapoints from a self-hosted OTel collector (delta temporality, OTLP/HTTP), compacted to daily Parquet and queried in Athena. Request counts are sums of datapoint counts, not row counts.
• Single 14-day window, all ~330 licensed users, no sampling. The window deliberately excludes an earlier period during which my own ingest was dropping traffic, so the shares aren't skewed by collection loss.
• Cost is Claude Code's own client-side estimate, not invoiced spend.

Related issues:

• #59942 — query_source missing on api_request events and cost/token counters; documents the observed enum values and the event-vs-metric schema split. My question 5 is likely the same underlying behaviour.
• #63536 — includes a real main / auxiliary / subagent cost breakdown, and shows query_source: "repl_main_thread" on an event that rolls up to the main metric bucket.

Happy to share more of the breakdown if it would help pin down what the bucket contains.