Querying the audit log
query_logs is the flight recorder's filter: it returns the rows that match an agent, a verdict or a time window, and get_statistics summarises the whole log.
Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0
The flight recorder lesson wrote three decisions. Once a log has thousands, you want the blocked ones, or one agent's actions, not the whole file. That is what querying gives you.
Filtering by agent and by verdict
query_logs takes optional filters and returns the matching rows. With no filter it returns everything up to its limit; with policy_verdict it returns only that verdict.
for_shop = recorder.query_logs(agent_id="shop")
print("all for shop:", len(for_shop))
# the verdict stored for a blocked call is the string "blocked"
blocked = recorder.query_logs(policy_verdict="blocked")
print("only blocked:", len(blocked))
print("blocked tool:", blocked[0]["tool_name"])all for shop: 3 only blocked: 1 blocked tool: delete_account
Summarising the whole log
get_statistics reads the whole log and returns counts, so you do not have to tally rows yourself. by_verdict is the breakdown, and total_actions is the count.
stats = recorder.get_statistics()
# the counts are computed across every row in the log
print("by verdict: ", stats["by_verdict"])
print("total actions:", stats["total_actions"])by verdict: {'allowed': 2, 'blocked': 1}
total actions: 3query_logs vs get_statistics
| query_logs | get_statistics | |
|---|---|---|
| Returns | The matching rows | Counts and averages |
| Use it for | Reading specific decisions | A dashboard number |
| Filters | agent, verdict, time, limit | None, it reads all |
Where you use querying
- An alert that fires when the count of blocked calls in the last hour crosses a threshold.
- A per-agent view, pulling one agent's history out of a shared log.
- A daily summary, reading
by_verdictfor the headline numbers.
query_logs has a limit that defaults to 100, so a busy log can return a truncated view. Pass a larger limit, or narrow with a time window, when you need every match.Related
- Query with
policy_verdict="allowed"and confirm the count is two. - Add more calls, then pass
limit=1and see the result truncate. - Read every key in
get_statistics()and find the average execution time.
Little by little, you're building something great.