--- title: "getAgentUsageBreakdown" description: "Break down project usage by agent credential" canonical: "https://pgbeam.com/docs/ts-sdk/agents/getAgentUsageBreakdown" last-updated: "2026-09-13T16:16:22.000Z" --- # getAgentUsageBreakdown > Break down project usage by agent credential URL: https://pgbeam.com/docs/ts-sdk/agents/getAgentUsageBreakdown Aggregates the audit trail into per-agent usage for a window: statements by decision, rows and bytes returned, the cache outcome breakdown, and latency percentiles. Read-only, derived entirely from entries the gateway already records. Grouped by credential, not by session. `session_id` is 32 bits of randomness minted per connection, so it identifies a connection rather than an agent or a run, and at scale it collides; the credential is the only stable identity in the trail. This endpoint reports usage and deliberately attributes no dollar figure to an agent. Overage is computed on the organization's total against a plan limit, so no single agent causes it independently of the others, and any per-agent split of that bill is a policy choice rather than a measurement. The organization's limits and marginal rates are returned alongside the usage so a caller can apply its own policy, with both meanings of a zero limit already resolved. Three things are reported rather than assumed. Usage recorded against no credential is its own line, so agents plus unattributed equals totals exactly. Latency covers only entries that ran and carried a finite value: every refusal writes a literal zero because there was nothing to time, and counting those would drag an agent's percentiles toward zero in proportion to how often it was refused, so the heavily blocked agent would report the fastest queries. And gap markers left by undelivered entries set `complete` to false, since a total over a trail with holes in it is a floor, not a measurement. Both `start` and `end` are optional. Omitting `end` means now; omitting `start` means 30 days before the end. The window is half-open and is capped at 92 days, because this aggregate reads every row in the window on the request path and an unbounded one would sort a year of latencies per group. `requested_start` and `requested_end` echo the window that was actually used, so a caller that pinned neither still knows what the totals cover. ## Usage ## Parameters Parameter Type Required Description pathParams.project\_id `string` Yes Unique project identifier (prefixed, e.g. prj\_xxx). queryParams.start `string` No Return entries at or after this timestamp (inclusive lower bound). queryParams.end `string` No Return entries strictly older than this timestamp (cursor / upper bound). ## Response `Promise`: per-agent usage for the window. ## Example ## Errors Status Description 400 The request was rejected. `code` is `INVALID_INPUT`, and `errors` names the offending fields when the failure was a validation one. 401 Missing or invalid authentication. `code` is `UNAUTHORIZED`. 403 The caller is authenticated but not allowed to perform this operation. `code` is `FORBIDDEN` when the caller's role is insufficient, and `PLAN_LIMIT_REACHED` when the organization's plan is what stands in the way. The two are answered differently, so branch on the code rather than the status. 404 The resource does not exist, or the caller is not entitled to know that it does. `code` is `NOT_FOUND`. 429 Rate limited. `code` is `RATE_LIMITED`. 500 The request failed for a reason on our side. `code` is `INTERNAL_ERROR`. Quote `request_id` when reporting it.