Usage and logs
Monitor Gateway usage, review request logs, and configure budget limits.
The Gateway records every request, each provider attempt, and cost estimates for observability and budgeting. You can review these records in the Gateway dashboard.
Request logs
Every Gateway request produces a request log entry containing:
| Field | Description |
|---|---|
| Request ID | Unique Gateway-internal identifier (gwrun_*). |
| Trace ID | Trace identifier (gwtrace_*) shared across logs and responses. |
| Model | The model ID requested. |
| Provider | The provider that served the request. |
| Status code | The HTTP status returned to the client. |
| Latency | Total round-trip time in milliseconds. |
| Tokens | Input and output token counts (when reported by the provider). |
| Estimated cost | Computed cost in USD from the model catalog pricing data. |
| Fallback used | Whether the request fell back to a secondary provider. |
| Error code | Machine-readable error code on failed requests. |
Logs can be filtered by project and ordered by recency.
Provider attempt logs
Each provider attempt within a request is recorded separately:
| Field | Description |
|---|---|
| Attempt number | Sequential attempt index (1-based). |
| Provider ID | The provider that was called. |
| Model | The model alias used for this attempt. |
| Succeeded | Whether the provider call returned a successful response. |
| Error code | Machine-readable error code on failure (e.g. provider_unavailable, provider_timeout). |
| Error message | Redacted human-readable error message (sensitive details scrubbed). |
| Latency | Provider response time in milliseconds. |
These records let you diagnose why a request failed and which provider eventually served it.
Usage tracking
Each request also produces a usage event tracked in the gateway_usage_events table. The Gateway computes usage summaries broken down by:
- Project — total usage across all keys and routes for each project.
- Model — usage per model ID.
- Provider — usage per provider.
Each summary row includes request count, input tokens, output tokens, and estimated cost in USD.
Usage totals are visible on the Gateway dashboard Overview page.
Budget limits
Projects can configure spending limits. The Gateway supports three limit types:
| Limit type | Scope | Description |
|---|---|---|
daily_usd | Per project | Total estimated cost in a UTC calendar day. |
monthly_usd | Per project | Total estimated cost in a UTC calendar month. |
monthly_tokens | Per project | Total tokens (input + output) in a UTC calendar month. |
When a limit is exceeded:
- The Gateway rejects subsequent chat completion requests from that project.
- The response includes the exceeded limit type and current spend.
- The request log records the block with an error code.
Fail-closed behavior
When Supabase storage is unavailable and a project has budget configuration, the Gateway cannot determine spend status. In this case requests are denied by default. Local development can bypass this check by setting GATEWAY_BYPASS_BUDGET_CHECK=true.
Projects with no budget configuration are not subject to budget enforcement.
Data retention
Request logs and usage events contain metadata only (model, provider, tokens, cost, timestamps). Request and response content is never stored in the Gateway logging pipeline unless separately configured.