---
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-09-14T19:37:21.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; to flag unusual behavior automatically, see 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.

## 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:

## 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.

Audit retention depends on your plan: 7 days on Starter, 30 days on Pro, and
90 days on Scale. See 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: HMAC-signed webhooks and SIEM formats.

Anomaly detection: alert on drift from baseline.

Approvals: every approval decision is recorded here.

Policies

Kill-switch

Plans