Usage

The Usage page shows what agents are loading, from where, and what it costs. Observe → Usage.

All four libraries meter here — entity loads, brief and skill retrievals, and catalog reads — in one table, told apart by the Library filter.

By entity

Two charts and a daily table, filtered by Domain, Library, Artifact, Surface, Level, Format and a timeframe. Library picks the shelf; the Artifact menu follows it, so choosing Skills offers only skills.

The table splits each day into Markdown Loads / Tokens, JSON Loads / Tokens, and totals. JSON repeats every key on every row, so the split shows whether a rising bill is more traffic or a shift in encoding.

Export CSV gives the full per-row breakdown, including the artifact, its library, format, and the version each row served.

Activation markers

Filter to a single entity and the charts mark each activation — a dashed line with the version number where a new version started serving — so you can compare token cost before and after a change. Every load is stamped with the version it served, and the export carries it per row, even after a rollback. A load served from a never-activated draft carries no version.

By user

A scope toggle switches to By user: one row per caller, ranked by tokens, with Top consumers charts. Filter by Domain, Library, Artifact, and a user search.

ColumnWhat it is
UserThe caller. For an agent, the user the agent runs as
Loads / TokensTotal consumption over the timeframe
Tokens / loadHeavy payloads, or many light ones
Entities / Top entityHow broad their usage is, and where most of it goes
ErrorsFailed loads — a lone high error rate usually means a permissions problem

The two scopes are separate rollups of the same traffic — never add them together. The export follows the toggle: usage-*.csv carries format and surface; usage-by-user-*.csv carries day and entity per person.

Agentforce passes no agent identity to Apex, so the running user is the only per-agent signal — give each agent its own user before the second one goes live. See Agentforce.

NOTE

Per-user rollups are on by default. To switch them off, set entity_track_user_usage to false — org-level rollups keep working.

The dimensions

  • Library — Entities, Briefs, Skills, or Catalog. Only libraries with traffic in the window are offered.
  • Artifact — which entity, brief, or skill. No traffic on a named view means nothing is asking for it. Catalog reads file under one artifact, (catalog).
  • Surface — agentforce, mcp, apex, a toolName you set on your own caller, or the tool itself: get_briefs, get_skill, get_catalog.
  • Level — mostly detailed, the default. Find Records calls log as query, and its grouped/summary calls as aggregate — a healthy share of either means agents are asking about sets instead of loading records one at a time. Catalog reads log the call’s shape instead: index (the whole catalog), detail (named entities), or unchanged — the agent echoed a current version stamp and was served two lines instead of the catalog, the token saving working as designed.
  • Format — markdown, JSON, or both. A both row is ONE load that served both encodings; it is its own value rather than a flavour of JSON, so it cannot be mistaken for a call that paid for one.
  • Domain — which domain the call came through.

What to look for

  • Tokens per load, by entity. A detailed Account 360 is typically 400–900 tokens. Well past that, look for an unfiltered related list or a high max-rows setting.
  • One entity dominating. Fine if it’s your main use case. If not, agents may be loading records in depth when a query would answer — fix the instructions, not the configuration.
  • Traffic you didn’t expect. Heavy load on a neglected entity makes its curation worth improving.
  • Catalog reads with no unchanged rows. Agents that never echo the version stamp re-download the whole index every session — a caller-side fix worth the tokens it saves.
  • Nothing at all. No usage means the action was never reached. Failures show on Issues.

Reducing cost

In rough order of return:

  1. Filter related lists. The biggest lever — an unfiltered 25-row list can be half a payload.
  2. Lower max rows. Five to ten is usually plenty.
  3. Convert lists to metrics. One number can replace twenty-five rows.
  4. Drop low-completeness fields. Quality names them.
  5. Reconsider references. A parent embedded at standard is a whole second field list.
  6. Raise element minimum levels to keep depth-only enrichments off leaner payloads.

Don’t cut instructions — they’re cheap and the highest-value tokens in the payload.

Assembly time lives on the Performance page, which shares this page’s filters.

What’s next