This guide will cover the request log, usage summaries, and per-end-user cost breakdowns, and how privacy modes shape what you can see. Observability reads come from the async analytics tables (request_logs, usage_rollups) through the tenant funnel, so they never touch the gateway hot path and RLS keeps one org from ever reading another’s data. Every route below is on the control plane , gated at logs.read (member or above).

​
Usage & cost summary

GET /v1/projects/{projectId}/usage/summary aggregates the durable rollups (never a raw scan), grouped by any subset of day, model, and env.
  • group_by — a comma-separated subset of day, model, env (defaults to day).
  • granularity — hour or day.
  • from / to — the window (defaults to the last 30 days); env — narrow to one environment.
Each row carries requests, errors, tokens_in, tokens_out, cost_usd, and estimated_requests. cost_usd is the gateway-computed per-request cost — useful for cost analytics even though billing meters requests, not tokens.

​
Request logs

GET /v1/projects/{projectId}/logs returns a cursor-paginated page of request metadata (status, model, latency, end user, error code — no payload).
Filters: env, status (error matches any non-ok), model, end_user (the external id), error_code, from, to. Page forward with the returned next_cursor. Fetch one request’s detail — including its prompt/response payload (subject to the privacy mode) and any aggregated feedback — with the request id:
The request_id is the same X-Request-Id returned on the original data-plane response (and surfaced by the SDK as result.requestId), so you can jump straight from a failing call to its log.

​
Per-end-user cost

Because every request is attributed to an end user, cost and usage roll up per user. The dashboard renders your top users by spend or volume and per-user usage over time — the same data your support team uses to answer “why is this user’s bill high?”. Over the API, filter the request log by end_user to see one user’s traffic:
See End users & entitlements for how attribution works.

​
How privacy modes shape what you see

What a log’s detail contains was decided by the privacy mode when the metering worker wrote it — the read path only ever exposes what the mode permitted: Development environments default to full; production defaults to metadata. So in production you will typically see rich metadata and cost, but no prompt content unless you opted in. Image bytes are never logged in any mode — only the prompt, an [omitted:image] marker, and generation metadata.
The usage record (tokens, cost, status) is always kept regardless of privacy mode — it is what metering and billing run on. Privacy governs prompt/response content, not metrics.

​
Erasing content

To delete log content (for a data-subject request), POST /v1/projects/{projectId}/logs/purge with exactly one selector — a single request_id, one end_user, or an entire env. This is admin-gated (logs.purge) and deletes request logs and their externalized payload objects only; it never touches usage or billing records. See Privacy & compliance.

Privacy modes

Full, redacted, metadata, or none — per environment.

Observability tutorial

A hands-on walkthrough of logs and usage.

Set usage controls

Turn what you observe into enforced limits.

Billing & plans

What is metered and how it is billed.