# Usage and logs

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.

## See also

- [Gateway overview](/docs/gateway/overview)
- [Authentication and API keys](/docs/gateway/authentication)
- [Providers, routing, and fallbacks](/docs/gateway/providers)