Data handling and retention
Configure how the Gateway handles request data, logging modes, content retention, and zero-data-retention mode.
The Gateway provides configurable data handling to match your project's privacy and compliance requirements.
Request logging
Every Gateway request produces a request log record containing:
| Field | Description | Stored by default |
|---|---|---|
| Request ID | Unique Gateway-internal identifier (gwrun_*) | Yes |
| Trace ID | Shared trace identifier (gwtrace_*) | Yes |
| Model | The model ID requested | Yes |
| Provider | The provider that served the request | Yes |
| Status code | HTTP status returned to the client | Yes |
| Latency | Total round-trip time in milliseconds | Yes |
| Tokens | Input and output token counts | Yes |
| Estimated cost | Computed cost in USD | Yes |
| Fallback used | Whether a secondary provider was used | Yes |
| Error code | Machine-readable error on failures | Yes |
Request and response content is never stored in the Gateway logging pipeline unless a separate content-logging configuration is enabled.
Logging modes
Projects can configure a loggingMode through the Gateway settings:
| Mode | Effect |
|---|---|
metadata_only | Logs metadata fields only (tokens, latency, cost, status, error codes). No message content or model responses are recorded. Default. |
content | Logs request messages and response content in addition to metadata. |
off | Disables request logging entirely. Usage tracking and budgets still operate from in-memory counters. |
Content retention
When a project configures contentRetentionDays, logged content (messages and responses) is retained for that number of days before automatic deletion. A null value means content is retained indefinitely.
Metadata-only fields (request IDs, timestamps, tokens, cost) are not subject to content retention — they follow the project's audit log retention policy.
Zero-data-retention mode
Set zeroDataRetention: true in the Gateway settings payload to minimise data persistence:
- Request logs are written with metadata only regardless of the
loggingModesetting. - Provider attempt logs do not store error message details.
- Usage summaries continue to aggregate token and cost counts for billing, but individual request detail is not recoverable past the current aggregation window.
Usage tracking
Even with logging off, the Gateway records usage events for billing and budgeting:
- Count of requests per project, model, and provider.
- Input and output token totals.
- Estimated cost in USD.
Usage data is stored in the gateway_usage_events table and aggregated for dashboard display. Individual usage events cannot be linked back to specific request content.
Budget enforcement
Projects can configure spending limits (daily_usd, monthly_usd, monthly_tokens). 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.
When Supabase storage is unavailable and a project has budget configuration, the Gateway cannot determine spend status and fails closed — requests are denied unless GATEWAY_BYPASS_BUDGET_CHECK=true is set (local development only).
Fail-closed data handling
The Gateway applies a consistent fail-closed policy for data-handling features:
| Feature | When storage unavailable |
|---|---|
| Budget enforcement | Deny requests (bypassable in dev with env var) |
| Provider allowlist enforcement | Deny requests (bypassable in dev with env var) |
| BYOK credential lookup | Credentials unavailable; fall back to server-level env vars |