Audit Logs
The Audit Logs page gives you a full, timestamped record of every action your agents and integrations have performed — authentication events, tool calls, configuration changes, MCP requests, and system-level operations. Use it to verify that agents are behaving as expected, investigate anomalies, and maintain a compliance record of all activity.
What audit logs track
Every significant operation on the Balchemy platform emits an audit log entry. The audit system covers five action categories:
| Category | What it includes |
|---|---|
auth | Wallet sign-ins, session creation, token refresh, logout, and step-up authentication challenges |
trade | Order creation, approval, cancellation, and fill events from all channels |
config | Bot configuration changes, API key creation and revocation, scope modifications |
mcp | Every MCP tool call including the tool name, calling agent, and result |
system | Platform-level events — kill switch activations, circuit breaker state changes, rate limit hits |
Log entry fields
Click any row in the log table to open the detail drawer. Each log entry contains the following fields:
| Field | Description |
|---|---|
| Timestamp | ISO 8601 timestamp with millisecond precision. Recent events (under 24 hours) show as relative time (e.g., "3 minutes ago"); older events show as MMM D, HH:mm. Hover for the full UTC timestamp. |
| Actor | The identity that performed the action — your user account, an agent identified by agentId, or system for platform-initiated events. |
| Action | The specific operation performed (e.g., mcp.tool.call, order.created, api_key.revoked, bot.config.updated). |
| Action Type | The category the action belongs to: auth, trade, config, mcp, or system. |
| Target | The object the action was applied to — a bot ID, order ID, API key name, or other resource identifier. |
| Result | The outcome of the action: success, failure, or partial. All result badges pair a color with an icon — green check for success, red X for failure, amber triangle for partial. |
| Duration | Time taken to process the request, shown in the detail drawer when available. |
| Correlation ID | A UUID that links this event to a distributed trace. Use this ID to find the corresponding trace in Grafana/Tempo if you have observability access. |
| Request ID | The unique ID of the HTTP or gRPC request that generated this event. |
| Session ID | The session associated with the request, when applicable. |
| Source IP | The originating IP address of the request, when available. |
| Event Payload | The structured JSON payload attached to the event — expandable in the detail drawer. Sensitive fields such as key secrets and wallet keys are redacted before reaching the audit log. |
Navigating the logs page
Open Hub and click Logs in the left navigation. The page loads the last 7 days of events by default.
Filtering
The sticky filter bar at the top of the page provides four controls:
- Date Range — select Last 24h, Last 7 days, Last 30 days, or All Time
- Actor — filter to events from a specific agent or user
- Action Type — filter to a single category (auth, trade, config, mcp, system)
- Search — full-text search across action name, actor, and target fields
Filters combine — for example, you can show only mcp events from a specific agent in the last 24 hours. When active filters are applied, a Clear All link appears to the right of the filter bar.
You can also navigate directly to a filtered view from the Agent Detail page — the activity log link passes a botId query parameter (e.g., /hub/logs?botId=YOUR_BOT_ID) to pre-filter the log to that agent's events.
Sorting
Click any sortable column header (Timestamp, Actor, Action, Result) to sort the table. Click again to reverse the sort direction. Click a third time to remove the sort and return to default (newest-first).
Row interaction
Click any table row or card (mobile) to open the detail drawer on the right. The drawer shows the full event details including all correlation metadata and the expandable JSON payload. Click the copy icon next to the Correlation ID or Request ID to copy the full value to the clipboard.
On mobile, the table switches to a card layout. Each card shows the action, result badge, actor, target, truncated correlation ID, and relative timestamp.
Investigating suspicious activity
When an agent behaves unexpectedly, the audit log is your primary investigation tool. A typical workflow:
Step 1 — Filter by actor. Select the specific agent from the Actor dropdown. This isolates all activity from that agent.
Step 2 — Look for failure results. Sort by Result or filter visually for failure badges. Failures indicate rejected tool calls, blocked trades, or authentication problems.
Step 3 — Examine the event payload. Click a failure row to open the detail drawer and expand the Event Payload section. The payload typically contains the error message, the tool name (for MCP failures), or the policy reason (for blocked trades such as "Circuit breaker is open for provider: jupiter").
Step 4 — Cross-reference with Correlation ID. Copy the Correlation ID and search for it in your observability stack (Grafana Explore → Tempo). The correlation ID links the audit event to the full distributed trace, showing every service call involved in the operation.
Step 5 — Check scope. If an agent is receiving 403 Forbidden failures on tool calls, verify that the API key used by the agent carries the correct scope. A read-scoped key cannot call trade tools. See Scopes and Access Control for the scope-to-tool mapping.
Log retention
Audit logs are stored in the platform's MongoDB database. The default retention window is 30 days of queryable history through the Hub UI. The date range filter caps at "All Time," which queries the full available window.
For compliance use cases requiring longer retention, export logs programmatically using the REST API (see the code example below) and archive them to your own storage.
Fetching logs via API
You can retrieve audit logs programmatically using the REST API. This is useful for building monitoring scripts, exporting to a SIEM, or correlating log data with your own systems.
# Fetch the last 100 audit log entries
curl https://api.balchemy.ai/api/audit-logs?limit=100 \
-H "Authorization: Bearer YOUR_SESSION_TOKEN"
# Filter by action type and date range
curl "https://api.balchemy.ai/api/audit-logs?action=mcp&startDate=2026-03-01T00:00:00Z&limit=500" \
-H "Authorization: Bearer YOUR_SESSION_TOKEN"
# Filter by a specific actor (agent ID or user ID)
curl "https://api.balchemy.ai/api/audit-logs?actor=AGENT_ID&dateRange=7d" \
-H "Authorization: Bearer YOUR_SESSION_TOKEN"
# Filter by bot ID (same as agent detail → logs link)
curl "https://api.balchemy.ai/api/audit-logs?botId=BOT_ID&limit=100" \
-H "Authorization: Bearer YOUR_SESSION_TOKEN"The API response is an array of log entry objects. Each object matches the field schema described in the Log Entry Fields section above.
Supported query parameters:
| Parameter | Type | Description |
|---|---|---|
action | string | Filter by action string or type category |
actor | string | Filter by actor ID |
botId | string | Filter by bot ID — used by agent detail page links |
search | string | Full-text search across action, actor, and target |
startDate | ISO string | Filter events after this timestamp |
endDate | ISO string | Filter events before this timestamp |
dateRange | 24h | 7d | 30d | Convenience range (overridden by startDate) |
limit | number | Maximum number of results to return |
offset | number | Number of results to skip (for pagination) |
Monitoring tips
Set up a daily review cadence. Spend five minutes each day reviewing the last 24 hours of failure events for your most active agents. Most operational issues surface as a pattern of failures before they become serious problems.
Watch for authentication failures. A sudden spike in auth failures for a specific agent may indicate that its API key was rotated, revoked, or misconfigured. Navigate to Hub API Keys and confirm the key is active and that the agent is using the correct credential.
MCP scope failures signal a misconfigured agent. If mcp.tool.call events show repeated failure results with a scope error, the agent is attempting to call tools it does not have permission for. Either adjust the agent's code to use only the tools its key scope allows, or create a higher-scope key for that agent.
Use correlation IDs for support requests. If you need to report a platform issue to the Balchemy team, include the Correlation ID from the affected event. This allows the team to locate the exact trace and diagnose the root cause efficiently.
Related pages
- API Keys — create and manage the credentials that generate MCP log entries
- Scopes and Access Control — understand which tools require which scope, and why scope failures appear in logs
- Order Lifecycle — trace a trade event from audit log entry through the full execution pipeline
- Error Codes — decode the error codes that appear in log event payloads