Skip to Content

Usage and logs

Open Usage for the selected Live/Sandbox mode. The report answers which projects or customers generated recorded requests; it is separate from the Client SDK’s current customer allowance.

Filter and drill down

Choose a day, week or month range, then select a grouping. Structured filters restrict the server query by fields such as project or outcome. Select a Requests or Failed requests count to open matching request logs. Choose no grouping to work directly with individual requests.

Text search within a loaded request log filters the rows already downloaded. It does not search every stored request. Request history is paginated; load older rows with Live off. The current reporting defaults cover up to 30 days and load up to 1,000 activity rows. These are reporting limits, not a promise that older storage was erased.

A report can flag truncated groups, partial cost coverage or a failed refresh. Read those notices before using displayed totals as complete results. Unknown or unavailable cost is not zero.

Live refresh

Live starts off. When enabled, it normally polls every ten seconds, slows to thirty seconds after six unchanged reads, and turns off after ten minutes. Loading older request pages requires Live off. Enabling Live discards older loaded pages so the log can follow current requests.

A paged log keeps the time-window end from its first page. Turn Live on or choose a new window to return to current activity. Refresh failures can leave the previous result visible with a warning.

Content retention

Request metadata and customer content are separate. A normal customer request can have a stored request ID, model, timing, outcome, token usage and estimates without retaining its prompt or output text. Missing text is not proof that generation failed or used zero tokens.

The gateway enables content retention only after authenticating a synthetic customer in a Sandbox project. Ordinary Live requests and ordinary customer sessions in Sandbox do not opt in. Setting a Sandbox header alone does not enable it, and permission to read logs does not change the request’s content policy.

For supported synthetic debug requests, completion text or speech input text can be retained. This does not promise full transcripts, binary audio, every protocol’s body or unlimited text. Retained debug text can be truncated. Use test content appropriate for the people who can access the project.

Completion log events make omission explicit:

{ "content": { "retained": false, "omissionReason": "privacy_policy" } }

That marker means the content was deliberately omitted, not that the model returned an empty answer. Provider HTTP failure events report status/metadata without copying the provider response body.

Live tails and stored records

Gateway log streams are a project event buffer, separate from the app’s stored request/usage records. The current source trims the tail to approximately 10,000 events per project by count; it does not promise a fixed number of hours or days. A cursor can fall behind that buffer even while a request remains visible in Usage.

Stored reporting has its own query windows and pagination, described above. Those display limits are not a storage-deletion schedule. Backups can include selected stored request data, but cannot recover text that was never retained or reconstruct trimmed live-tail events. These rules describe Modem’s gateway records, not content handling by your application or the upstream provider.

Read a request

Open a request to inspect its ID, project, customer, model, timing and outcome. Keep its request ID when correlating an app event, gateway response and CLI logs. The ID identifies a request; it is not an authorization credential.

Current request records distinguish these outcomes:

OutcomeInterpretation
PendingFinal accounting has not yet been recorded
CompletedThe request completed; inspect its recorded usage and pricing details
InterruptedThe response or accounting could not establish ordinary completion
FailedRequest execution failed
RejectedThe request was refused
Rate limitedA rate or admission limit refused it
Usage limit reachedAn applicable allowance refused it
SuspendedCustomer access was suspended

Outcome and HTTP status answer different questions. Receiving HTTP headers does not prove generation was accepted, and a 200 stream can still end in an error. See Gateway errors.

Separate requests from upstream attempts

The current source’s relay accounting includes upstream attempts marked accepted, quota-refused, authentication-rejected, rejected or unknown. Those fields require a server version that emits them; older deployments may omit them.

One admitted request can try more than one eligible subscription. Do not count each attempt as a separate customer request. Conversely, resending the request yourself creates another request and can generate again. A network failure with an unknown provider outcome is not permission to replay automatically.

Rejected-request history is sampled: at most one recorded row per customer and refusal outcome per second, and recording may be omitted when its guard is unavailable. It is useful for diagnosis, not an exact count of every refused HTTP call.

Quotas, credits and estimates

A request detail can show quota at admission, paid-credit use, token usage, an API-parity estimate and allowance reservation adjustments. These describe different things:

  • A quota observation describes the subscription when it was checked. It is not a reservation of provider capacity.
  • Permission to use paid credits, or selecting credit funding, does not prove the provider charged credits. An unknown paid-credit result stays unknown.
  • An API-parity estimate prices observed tokens using reference API rates. It is not a subscription invoice or a cash balance.
  • Reserved allowance is the amount held at admission. Metered or estimated settlement may adjust it; an unknown result is not automatically a refund.

See Limits and subscription quotas and credits for configuration and admission behavior.

Interrupted accounting

The current-source recovery path distinguishes undispatched work, explicit refusals and ambiguous dispatched work. After the request deadline and recovery delay, undispatched or recorded all-refused work can release its reservation. Work that may have reached the provider remains interrupted with unknown provider usage and retains its reservation; lost usage is not reconstructed as zero.

A completed response and a completed deferred settlement are not interchangeable. If a request remains pending or its accounting is unclear, retain its ID and inspect the record before retrying. Internal settlement retries use the same request ID to avoid repeating a committed debit; this does not make a new client request idempotent.

Last updated on