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

# Audit export

> Mirror every ValarCode exchange into an S3 bucket your organization owns, as full records or as metadata only

Audit export writes a copy of each completed ValarCode exchange into an Amazon S3 bucket that your
organization owns. Valar holds permission to add objects to that bucket and nothing else: it never
reads, lists or deletes there, including the objects it wrote. You decide who reads the bucket, how
long records live, and whether they are locked.

It is built for organizations that keep their own audit trail of what engineers send to models and
what comes back, typically feeding a SIEM. Audit export is enabled per organization by Valar; once
it is, admins configure it in **Settings > ValarCode > Audit export**.

## Two modes

| | Full | Metadata only |
| - | - | - |
| Objects per exchange | two: `.request.json` and `.response.json` | one: `.exchange.json` |
| Prompt, tool definitions, response text | included | never included |
| Who, when, which tool, request and session ids | yes | yes |
| Model asked for, model that answered, stop reason, token counts, latency | yes | yes |
| Message and tool counts, request and response sizes | derivable from the bodies | included as numbers |

Switch between them with **Metadata only** in the same panel. The switch takes effect on the next
request. Choose metadata only when you need attribution and volume rather than content, or when
full bodies would be a large share of your SIEM ingest.

## What a metadata record looks like

One object per exchange. This is a Claude Code turn that ended in a tool call:

```json theme={"system"}
{
  "timestamp": "2026-10-20T14:07:31Z",
  "exchange_id": "6f1d2c3b4a5968778695a4b3c2d1e0f9",
  "client_id": "dfox@example.com",
  "harness": "claude",
  "surface": "cli",
  "user_agent": "claude-cli/2.1.290 (external, cli)",
  "api": "/v1/messages",
  "request_id": "resp_01JAZ6M3Q9V7K2XH8P4N5W6D0",
  "session_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "status": 200,
  "latency_ms": 8420,
  "request": {
    "model": "claude-sonnet-5",
    "max_tokens": 32000,
    "stream": true,
    "messages": 12,
    "tools": 7,
    "bytes": 2056
  },
  "response": {
    "model": "claude-sonnet-5",
    "served_model": "zai-org/GLM-5.3",
    "stop_reason": "tool_use",
    "usage": {
      "input_tokens": 412,
      "output_tokens": 57,
      "cache_read_input_tokens": 38910,
      "cache_creation_input_tokens": 0
    },
    "bytes": 1259
  }
}
```

Field by field:

* `timestamp`, `exchange_id`: when the exchange completed, and the id in the object key.
* `client_id`: the engineer the key is attributed to. `harness`, `surface` and `user_agent` say
  which tool sent the request, read from the request itself.
* `request_id`: Valar's id for the request, the one to quote to support. `session_id`: the session
  id the tool sent, when it sent one (Claude Code does), so you can group a conversation.
* `status`: always `200`. Only exchanges whose response reached the client are exported, so a
  failed request never produces a record. A stream that was cut after it started still reads
  `200`, with `stop_reason` null.
* `latency_ms`: from Valar starting the response to its last byte.
* `request`: the model the client asked for and the request's shape. `messages` and `tools` are
  counts, `bytes` is the size of the body as sent. The messages, system prompt, tool definitions
  and metadata block themselves are not exported.
* `response`: the model name returned to the client, the model that answered, why it stopped,
  the token counts, and the size of what reached the client. `served_model` is present only when
  your organization has turned on **Show serving model name in the response body** in Settings;
  it names a model, never a provider.

## What a full record looks like

Two objects per exchange that share the same key prefix. The request object carries the same
attribution fields above and a `body` with the request exactly as the client sent it, before Valar
touched it. The response object carries the attribution, `latency_ms`, and a `body` with the
response as the client received it, limited to the standard fields of the Anthropic Messages API:
`type`, `role`, `model`, `served_model`, `content`, `stop_reason`, `stop_sequence` and the token
counts in `usage`. Inside `content`, each block keeps only its standard fields.

## What never leaves Valar

Records are built from a fixed list of fields rather than by removing fields from what an upstream
returned, so anything Valar has not explicitly allowed cannot reach your bucket, including fields a
future API version adds. In particular, nothing about how the request was served is exported: no
provider, no route, no cost, no internal identifiers. The upstream's own message id is not exported;
correlation uses `request_id` and the object key.

## Object layout

Objects are partitioned by hour in UTC:

```
2026/10/20/14/20261020T140731.250Z-6f1d2c3b4a5968778695a4b3c2d1e0f9.exchange.json
2026/10/20/14/20261020T140731.250Z-6f1d2c3b4a5968778695a4b3c2d1e0f9.request.json
2026/10/20/14/20261020T140731.250Z-6f1d2c3b4a5968778695a4b3c2d1e0f9.response.json
```

`_valar-access-check/last-check.txt` is a small text object that **Check access** in Settings
overwrites each time you run it. It contains no request data and can be excluded from ingest with
one prefix.

## Setting it up

1. Create the bucket in your AWS account, in a region listed in the Settings dropdown.
2. Add a bucket policy that grants `s3:PutObject` on the bucket's objects to the writer principal
   shown in **Settings > ValarCode > Audit export**. Nothing else is needed, and nothing else should
   be granted. If the bucket uses a KMS key, the key policy must also allow `kms:GenerateDataKey`
   and `kms:Encrypt` for the same principal.
3. Send the bucket name and region to your Valar contact. Valar allows each bucket on its side
   before the first write.
4. Enter the bucket name and region, choose **Metadata only** if you want it, and save.
5. Click **Check access**. Valar writes the access-check object and reports the result, which is
   also kept with the setting so the panel shows when the bucket was last verified.

The export never affects requests. If the bucket stops accepting writes, requests keep succeeding
and the records for that period are missing from your bucket; Valar monitors failed writes and
will tell you. Turn the export off with the switch at the top of the panel; the bucket stays
configured so turning it back on needs no new setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.