---
title: "Audit Log"
description: "Every statement an agent runs, allowed or blocked, recorded with its decision, reason, rows, bytes, latency, and credential."
canonical: "https://pgbeam.com/docs/audit-log"
last-updated: "2026-10-29T19:01:20.000Z"
---

# Audit Log

> Every statement an agent runs, allowed or blocked, recorded with its decision, reason, rows, bytes, latency, and credential.

URL: https://pgbeam.com/docs/audit-log

The audit log records every statement a credential runs through PgBeam, whether it was allowed, masked, blocked, or throttled. Each entry captures the SQL, the decision and the reason for it, the rows and bytes returned, the latency, and the credential that ran it. Recent entries are queryable in the control plane; older entries are archived for retention.

It covers agent and human credentials, and records each credential's `principal_type` so you can tell agent traffic from people. To stream events to your own systems in real time, see [audit export](/docs/audit-export); to flag unusual behavior automatically, see [anomaly detection](/docs/anomaly-detection).

## What is recorded

| Field      | Description                                              |
| ---------- | -------------------------------------------------------- |
| Time       | When the statement ran.                                  |
| Credential | The agent credential that ran it.                        |
| SQL        | The statement, as parsed.                                |
| Decision   | `allowed`, `masked`, `blocked`, or `throttled`.          |
| Reason     | Why it was blocked, masked, or throttled.                |
| Rows       | Rows returned to the agent (after masking and row caps). |
| Bytes      | Bytes returned.                                          |
| Latency    | Time to serve the statement.                             |
| Source     | Connection string or hosted MCP.                         |

A blocked statement leaves your database as it was. The one exception is `result_withheld`: with `content_scan_mode=block` on the policy profile, the statement ran, the scan found agent-directed content in a returned value, and the agent got an error instead of the result. A write it made has committed. Rows and Bytes on that entry count what the agent received before the refusal.

## Read the log

Open the **Audit** tab in the dashboard to filter by agent, decision, or time range and export the result. From the terminal or API:

```bash title="Read the audit log"
# CLI
pgbeam audit list --decision blocked --since 24h

# API
curl "https://api.pgbeam.com/v1/projects/{projectId}/audit?decision=blocked" \
  -H "Authorization: Bearer pbo_..."
```

## How the pipeline works

Each data plane captures the decision for every agent statement and ships it to the control plane. Recent entries are stored in control-plane Postgres for fast querying, and batched archives are written to object storage for long-term retention.

> **Retention by plan**
>
> Audit retention depends on your plan: 7 days on Starter, 30 days on Pro, and
> 90 days on Scale. See [Plans](/docs/plans). Archived entries remain available
> for export within your retention window.

## What it is good for

* Answer "what did this agent do" with the exact statements and decisions.
* Show a reviewer or security owner that an agent was held to its policy.
* Spot an agent that is hitting blocks or budgets and needs its policy adjusted.

## Related

* [Audit export](/docs/audit-export): HMAC-signed webhooks and SIEM formats.
* [Anomaly detection](/docs/anomaly-detection): alert on drift from baseline.
* [Approvals](/docs/approvals): every approval decision is recorded here.
* [Policies](/docs/policies)
* [Kill-switch](/docs/kill-switch)
* [Plans](/docs/plans)