Usage and audit metadata
These read-only REST endpoints are behind API_OPERATIONAL_READS_ENABLED=false by default. Their presence in OpenAPI does not establish deployment availability or provider accounting qualification. Send X-Api-Key; browser cookies are unnecessary. Existing read/operator/administrator profiles gain no reporting scopes.
Permissions
Path under /api/v1/agents/{agent_id}/ | Scope | Current authority |
|---|---|---|
usage/summary/, usage/requests/ | usage:read | Personal original owner, or Organization member issuer with VIEW_LLM_USAGE, or explicitly granted service |
audit-runs/, audit-runs/{run_id}/ | audit:read | Organization issuer with VIEW_AGENT_AUDIT, or explicitly granted service with retained original run attribution |
Create a Usage reporting, Audit metadata or Usage and audit metadata credential through the existing API key controls. Choose Application reporting to combine agents:read/agents:operate with both reporting scopes on the same principal for a continuous application-request workflow; it adds no configuration-management scope. Organization issuance still requires API-key and agent-management authority, recent browser authentication and the corresponding reporting capabilities. Member-issued keys recheck the issuer's complete scope set on every call. Service issuance/edit/enable/rotation requires an authorized human administrator; service reads recheck current service scopes and agent/active Team grants without depending on the human sponsor remaining employed. agents:read alone authorizes neither financial rows nor audit metadata.
Service receipts must retain the original Organization, agent UUID, owner and Team matching the currently granted agent. Changing its owner or Team does not give the new scope access to old receipts. Organization reporting members may read unknown historical owner attribution inside the retained original Organization. Service run reads require a prospective runtime-start snapshot proving the same original ownership; unknown historical runs without that attribution remain unavailable. No fleet-wide public reporting endpoint is included.
Queries and pages
Supply from and to as explicit offset-aware ISO8601 timestamps. from is inclusive, to exclusive, no later than now, with a maximum 31-day window. Usage time is dispatch receipt creation; audit time is run start. This is not a billing-period/invoice query. Unsupported or repeated fields fail validation.
curl --get "$BASE_URL/api/v1/agents/$AGENT_ID/usage/summary/" \
-H "X-Api-Key: $API_KEY" \
--data-urlencode 'from=2026-10-01T00:00:00Z' \
--data-urlencode 'to=2026-10-14T00:00:00Z'
List endpoints accept limit (1–100, default 50) and cursor. Repeat the same time/evaluation filters for subsequent pages. Cursors expire after 15 minutes and bind the principal, current scopes/resources/owner, filters, operation and creation watermark. Descending timestamp/UUID pagination avoids offset shifts; changing a filter or authority invalidates continuation. as_of is the creation watermark returned in period; supply it to reconcile summary against a paged inventory. It limits membership, not a snapshot of mutable counters/outcomes. Pending receipts can finalize and retention can remove records between calls; reconcile quiescent retained sources and restart after maintenance/backfill.
include_evaluations accepts only true/false, default false. Usage excludes explicitly marked eval receipts (eval_run_id_snapshot or environment eval); a missing environment remains unknown. Prospective run ownership snapshots retain the original environment. Legacy runs lack that snapshot; their default exclusion requires at least one retained receipt not marked eval. true includes other authorized run metadata. Both usage endpoints exclude historical aggregate receipts marked excluded_from_totals, preventing browser-summary double counting. Summary and paged rows share the same scoped selection.
No selected window can exceed 10,000 rows. Narrow the window after 503 operational_read_limit_exceeded. Shared HTTP quotas apply when enabled; PostgreSQL read/lock deadlines bound expensive reads even without that gate. There is no export job or unlimited count.
Accounting fields
Usage rows contain dispatch id, retained Organization/agent/owner/Team IDs, created_at, nullable run_id, model_attempt_id, processing_step_id, trigger_id and browser_task_id, purpose, configured/reported model/provider, outcome and nullable duration. These are source identifiers, not proof that an external effect succeeded.
tokens contains nullable prompt/completion/total/uncached/cached/cache-write/reasoning counters. measurement allowlists source, format, capture source, derived fields, warnings, not-applicable fields, completeness, environment, interruption, non-token activity, service tier and one-hour cache-write counts. Missing counters remain null. A measured zero remains zero; an empty selection has null subtotals and zero covered requests.
pricing preserves the selected source, USD currency, exact string rates per million tokens, revision/effective/selection times, pricing-model identity, catalog version/tier limitations, estimate notes/warnings and completeness when originally recorded. Historical receipts can lack their original basis; no current rate is substituted. estimated_cost is an exact decimal USD string from retained customer/public pricing; reported_cost is a separate provider monetary observation. Missing amounts remain null. Neither is an invoice or a guarantee of negotiated/provider accuracy. Non-token pricing and unobserved provider/gateway retries remain meaningful measurement gaps.
Summary metrics includes dispatch count, per-counter known subtotal/known/unknown/not-applicable coverage, and separately labeled known estimated and reported USD subtotals with priced/unpriced/reported/approximate counts. Reconcile these to the authorized rows, preserving each row's pricing source. Partial estimates cannot establish total lifetime cost.
Run metadata and request lineage
Run list/detail fields are original Organization/agent UUIDs, run UUID, status, coverage quality, trigger type, start/end timestamps and a nullable processing-step UUID from the retained process-events: correlation source. No initiator names, summary, prompts, event bodies, tool arguments, credentials or protected evidence are returned. A runtime status of succeeded does not prove downstream external success.
Both resources return application_request_ids only for the caller's explicit consumed application-request execution links with matching original Organization/owner. At most 100 per source step are returned; request_links_truncated flags additional retained links. A shared run's inference costs are agent/run accounting, not an allocation to each input request. Empty links mean no authorized retained link is known; identifiers are never inferred from nearby timestamps or conversations. Application-request content may be purged while its metadata identifiers remain; no content is reconstructed.
Retention and recovery
Responses are Cache-Control: no-store and cover currently retained authorized records. Original audit/inference and application-request retention policies still apply. Archived/deleted agents and agents transferred out of the original Organization are unavailable through this initial surface; original Organization historical reporting stays in the Console. Physically deleted resources return an indistinguishable 404, not a fabricated tombstone or lifetime-zero claim. Protected evidence reveal/export retains its existing separate permissions, logging, encryption and expiry. Managed SIEM forwarding remains a separate transport.
Errors use code: 400 invalid_operational_query, 403 missing_api_key_scope/operational_capability_required/organization_audit_required, 404 operational_resource_unavailable, 410 operational_cursor_expired, and 503 operational_reads_unavailable/operational_read_limit_exceeded/admission_unavailable. The shared-quota 429 request_quota_exceeded carries Retry-After. Invalid credentials can fail authentication before query validation.
Deploy 0587 with the read gate off, upgrade/drain audit writers and older readers and align admission/settings across the deployment. Explicitly grant reporting scopes, validate in a non-production environment, then deliberately enable the read gate. Rollback disables that gate and preserves source ledgers, grants, audit/application-request retention and generation fences. Apply additive 0587_audit_run_api_owner before upgraded/drained runtime audit writers and readers; no historical owner backfill is performed. This increment adds no charging/routing change, credit/budget enforcement, emergency-control operation or structured-result artifact.