Export billing Excel and troubleshoot logs

This chapter covers how to export the billing Excel from the console, filter and search logs, and correlate log entries by request ID. See Statistics and Logs viewer for the UI perspective of the statistics and logs pages, and Logs & body storage for the field reference on log body storage.

Export the billing Excel

Entry point: Console → Settings → Billing → Monthly cost (visible to admin and monitor).

Operations

1. In the month dropdown, select the month to export (the upper/lower bounds come from /statistics/range).
2. Click export.
3. You get an Excel with 6 sheets:

Sheet	Content
model	Aggregated by model
access key	Aggregated by access key
key group	Aggregated by key group
access key × model	Model distribution under each access key
day	Aggregated by day (split by browser local timezone)
week	Aggregated by week (browser local timezone, Monday as the start)

Each sheet's cost is split into columns by currency (Cost (USD), Cost (CNY)…), and each column's amount is the original value in that currency, with no cross-currency summation.

GET /console/api/billing/export, filename billing_{YYYY-MM}.xlsx.

Notes

• Only one export can be in progress per account at a time: when exporting concurrently across multiple tabs/devices or clicking repeatedly within a short time, the later request is told "export in progress, please try again later" (HTTP 429); the limit lifts immediately after the previous export completes.
• The month bounds come from /statistics/range, so you can only export months that have data. If the gateway was just deployed, it may not have a full month of data yet.
• count_tokens requests (the Anthropic token-count endpoint) are not counted in statistics, because they do not actually call an upstream and produce no cost — you won't see these requests in the exported Excel.
• Persistent statistics are stored in 1-minute buckets; the current minute's bucket is lost on a gateway crash, while completed minute buckets are kept.
• The monitor role can export (the billing page is visible to monitor, viewable and exportable), but cannot change any configuration.

Log filtering and search

Entry point: Console → Logs (visible to admin and monitor).

The logs page supports these filter methods:

Filter	Description
Time range	Select start/end time
Model	Filter by model name
Status code	Filter by response status code (2xx/4xx/5xx)
Access key	Filter by key name
Search	Search by request ID or other keywords

Live logs (SSE stream)

There is a Live logs toggle at the top right of the console. When on, all requests are pushed to the browser in real time:

• Transport over SSE (Server-Sent Events)
• Includes all requests (early failures like 401/429, internal endpoints, console routes)
• Unauthenticated requests show user: "anonymous"
• In a multi-instance deployment (Redis mode), aggregates request logs from all instances

With Live off it is polling refresh; with it on it is real-time push.

Request ID correlation

Every request has a unique z-request-id header (format <iso8601>-<uuid4>); that ID:

• Is injected into the request headers before the request enters processing
• Is mirrored to the response headers returned to the client
• Is forwarded to the upstream as an extra header
• Is embedded in all structured log entries

Enter the full request ID in the logs page search box to locate a specific request.

In practice: locating a client problem

When a client errors, have the client give you the z-request-id header from the response, then:

1. Go to Console → Logs page
2. Paste that ID into the search box
3. Find the corresponding request and click to expand its details
4. Look at the request / response / error details to locate the problem

Log details contain the full request/response lifecycle:

Tab	Content
Overview	Request ID, model, upstream URL, status code, latency, token usage, access key name/group
Client request	Request headers (sensitive values redacted) + request body
Upstream request	Translated request headers + request body (the actual content sent to the upstream)
Upstream response	Response status code + response headers + response body
Error	Error details for 4xx/5xx (truncated to 512 bytes)

Notifications

The top of the log details page shows special notifications for that request, e.g.:

• script_use_model_swap: this request's upstream model was switched by a script via context.useModel, not the model the client originally requested

FAQ

Q: The request count in statistics doesn't match the logs? Statistics aggregate at 1-minute granularity while logs record each entry. Within a short window there can be up to 1 minute of flush delay. count_tokens requests are visible in logs but not in statistics.

Q: Can't select a month for the Excel export? The month bounds come from /statistics/range, so you can only export months that have data. If the gateway was just deployed, it may not have a full month of data yet.

Q: Is the log list real-time? With the Live toggle on it is real-time push (SSE). With Live off it is polling refresh.

Q: Why is the body in the log truncated?logging.max_body_size_mb limits the captured size of each body (default 25 MB). Large bodies (such as long conversations, large embedding requests) are truncated. Raise this value to capture more, at the cost of more memory and disk. See Logs & body storage.

Q: Where do I see the response body of a streaming request? The streaming response body is recorded by a background task after the stream ends. If the stream is abnormally interrupted (client disconnect), the body may be incomplete (marked body_incomplete).

Q: Too many logs and the disk is nearly full — what now? Lower log_retention_days (e.g. 3 days) to speed up cleanup; lower stream_body_max_disk_mb to reduce streaming body disk usage. See Logs & body storage.

Q: How do I export logs (not the Excel)? The logs page itself has no Excel export entry (only the billing page does). To send logs out of the gateway, connect the SSE stream behind the logs page's Live toggle to your own collector; for single-entry troubleshooting use the z-request-id search.

Next: Statistics for the statistics page UI perspective; Logs viewer for the logs page UI perspective; Logs & body storage for the field and configuration reference.