> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verlon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs

> View detailed request logs with metrics, costs, and full request/response data

## Overview

Every request through Verlon is logged with comprehensive metadata. Logs let you inspect individual requests, debug issues, and understand how your gates are performing.

## Viewing Logs

Go to **Dashboard → Logs** to see a table of all requests with:

| Column      | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| **Status**  | Success or error                                                                |
| **Gate**    | Which gate handled the request                                                  |
| **Model**   | The model that was used (may differ from requested model if fallback triggered) |
| **Tokens**  | Input + output token count                                                      |
| **Cost**    | Estimated cost in USD                                                           |
| **Latency** | Response time in milliseconds                                                   |
| **Time**    | When the request was made                                                       |

### Filtering

Filter logs by:

* **Gate** — See requests for a specific gate
* **Status** — Show only successful or failed requests

### Pagination

Logs are paginated with 50 entries per page by default.

## Request Detail

Click any log entry to see full details:

### Overview

* Status, timestamp, gate name, model used
* Token breakdown (input/output), cost, latency

### Error Details

If the request failed, the error message and details are shown.

### Request Payload

The full JSON request sent to the provider, including:

* Messages array
* System prompt
* Tool definitions
* Model parameters (temperature, max\_tokens, etc.)

<Info>
  Prompt and response content is only present in your logs if you have
  opted in to payload storage in **Settings → Security & Privacy**. By
  default, only metadata is captured (see "Storage and retention" below).
</Info>

### Response Payload

The full JSON response from the provider, including:

* Generated content
* Usage statistics
* For image generation: inline preview with copy/download options
* For tool calls: extracted tool use blocks

## What's Tracked

Every request log captures:

| Field               | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `model_requested`   | Model specified in the request                                             |
| `model_used`        | Model that actually handled the request (may differ with fallback routing) |
| `prompt_tokens`     | Input token count                                                          |
| `completion_tokens` | Output token count                                                         |
| `cost_usd`          | Estimated cost                                                             |
| `latency_ms`        | Response time                                                              |
| `success`           | Whether the request completed successfully                                 |
| `error_message`     | Error details (if failed)                                                  |
| `tool_calls`        | Extracted tool use blocks from the response                                |
| `tool_results`      | Extracted tool results from the request                                    |

## Logs API

Query logs programmatically:

```bash theme={null}
# List recent logs
curl "https://api.verlon.ai/v1/logs?limit=20" \
  -H "Authorization: Bearer sk-vrln-your_key"

# Filter by gate
curl "https://api.verlon.ai/v1/logs?gateId=your-gate-id&limit=20" \
  -H "Authorization: Bearer sk-vrln-your_key"

# Get overview analytics
curl "https://api.verlon.ai/v1/logs/overview" \
  -H "Authorization: Bearer sk-vrln-your_key"
```

The overview endpoint returns aggregated stats:

* Total requests, total cost, average latency
* Active gate count
* Recent request summaries

## Storage and retention

Verlon's storage model is privacy-first by default.

### What is always stored

For every request, Verlon records **metadata only**:

* Gate id and gate configuration at request time
* Model used, token counts, cost, latency, success / error status
* Timestamps

This metadata powers your dashboard charts and stays available for as
long as your account is active.

### What is optional

The **content** of the request and response — the messages array, system
prompt, tool definitions, tool calls, tool results — is *not* stored by
default. To capture it for your dashboard logs, flip the **Store request
and response content** toggle in **Settings → Security & Privacy**.

When enabled:

* New requests are logged with their full prompt and response bodies.
* Content is wrapped in an AES-256-GCM envelope before being written to
  the database; the master key is held separately in the application
  environment.
* A nightly retention worker nulls payload columns once they age past
  30 days for free accounts. Metadata on those rows survives the sweep.
* Verlon does not scrub, modify, or filter the content you send. What
  you sent is what we store. You are responsible for deciding whether a
  given prompt is safe to send through us.

### Turning it off

Switching the toggle back to off stops *new* requests from capturing
content. Rows that were stored before the change continue to exist in
encrypted form until the nightly retention worker nulls them within
30 days.

### Internal access

Verlon employees cannot decrypt your stored payloads in bulk. The admin
listing tool returns metadata only; revealing a single row requires the
employee to pick a reason category and type a specific detail. Every
reveal writes an audit row before the decrypted content is returned.
Email [micah@verlon.ai](mailto:micah@verlon.ai) if you want a report of every internal view of
your account's data.