📋 Audit Log

Immutable agent action history for user-facing accountability.

How it works

Your agents log actions via a simple POST request. End users can then view a complete, tamper-proof history of everything the agent did. No edits, no deletes — once written, audit entries are immutable. This provides user-facing accountability without any extra infrastructure on your end.

Log an action

curl -X POST https://www.agent-utils.com/api/audit \

-H "x-api-key: au_your_key" \

-H "Content-Type: application/json" \

-d '{"agentName":"billing-agent","action":"refund_issued"}'

# Response

{"success":true,"data":{"id":"64f1a2b3c4d5e6f7a8b9c0d1"}}

List logs with filters

# List all (paginated)

curl https://www.agent-utils.com/api/audit \

-H "x-api-key: au_your_key"

# Filter by agent, action, severity, date range

curl "https://www.agent-utils.com/api/audit?agent=billing-agent&severity=warn&limit=20" \

-H "x-api-key: au_your_key"

Get a single entry

curl https://www.agent-utils.com/api/audit/${id} \

-H "x-api-key: au_your_key"

Parameters

Param	Method	Type	Description
action	POST	string	Required. Description of the action taken
agentName	POST	string	Name of the agent. Default: `unknown`
target	POST	string	What the action was performed on (e.g. resource ID)
metadata	POST	object	Arbitrary key-value data attached to the entry
severity	POST	string	`info` · `warn` · `error` · `critical` — default: `info`
agent	GET	query	Filter by agentName
action	GET	query	Filter by action
severity	GET	query	Filter by severity level
startDate / endDate	GET	query	ISO date strings to filter by createdAt range
limit / offset	GET	query	Pagination (default: limit=50, offset=0, max limit=100)

Python

import requests

requests.post(

"https://www.agent-utils.com/api/audit",

headers={"x-api-key": "au_your_key"},

json={

"agentName": "billing-agent",

"action": "refund_issued",

"target": "invoice_7842",

"metadata": {"amount": 49.99},

"severity": "info"

}

)

Immutability guarantee

Audit log entries cannot be modified or deleted via the API. There are no PUT, PATCH, or DELETE endpoints. This ensures a trustworthy trail of agent actions for compliance and debugging. Retention varies by tier: 30 days (Free), 90 days (Builder), 365 days (Pro), unlimited (Enterprise).