> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsentinel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Activity Ledger

> Complete audit trail of all agent actions with advanced filtering and export.

## Overview

The **Activity Ledger** provides a unified, chronological view of **all actions across all runs**. It's your complete audit trail with powerful filtering, search, and export capabilities.

## Dashboard stats

At the top, 6 metrics summarize ledger data:

| Stat | Description |
| - | - |
| **Total Actions** | Count of all actions logged |
| **Total Cost** | Sum of all costs (USD) |
| **Success Count** | Actions with outcome="success" |
| **Error Count** | Actions with outcome="error" |
| **Blocked Count** | Actions blocked by policies |
| **Avg Duration** | Mean execution time |

Additional stats:

* **Unique Agents** - Count of distinct agent\_ids
* **Unique Action Types** - Count of distinct action names

## Gateway decisions timeline

Above the ledger, the **Gateway decisions** timeline lists every authorization decision the gateway made across your organization, newest first. Each agent's details page shows the same timeline scoped to that agent.

Each row shows:

* **Time** and **Action**
* **Decision** badge: `allow`, `deny` or `require approval`
* **Reason** code explaining the decision
* **Approval** request opened (or redeemed) by the decision, linked to the Approvals page
* **Reserved**, **Actual** and **Remaining** budget in USD. A `—` means no value was recorded (for example, no reservation, or headroom not captured), not \$0.
* **Chain** status for the row:
  * **verified**: the row hash matches and the signature verifies
  * **unsigned**: the row has no signature (whatever its hash)
  * **failed**: a signed row whose hash or signature doesn't check out

Filter by decision with the dropdown. **Load more** appends the next older page.

The chain column checks each decision row on its own. To verify the whole hash chain, linking every row to the one before it, use **Verify chain**.

## Advanced filtering

The ledger's power is in its **comprehensive filtering system**:

### Filter by outcome

* **Success** - Completed successfully
* **Error** - Failed with exception
* **Blocked** - Prevented by policy
* **Replayed** - Executed via replay mode

Combine multiple outcomes (e.g., show errors + blocked).

### Filter by action name

* **Exact match** - Type action name
* **Auto-complete** - Suggests from existing actions
* **Case-sensitive**

Examples:

* `call_llm` - All LLM calls
* `search_web` - All web searches
* `transfer_funds` - All fund transfers

### Filter by agent

* Select from dropdown of known agents
* Type to search by agent\_id
* Shows display name if set

### Filter by run

* Enter run\_id
* Shows only actions from that specific run
* Useful for drilling down from Runs page

### Filter by cost range

Set min and max cost:

* **Min cost** - Show actions costing at least this much
* **Max cost** - Show actions costing at most this much

Examples:

* Min: \$0.10 - Expensive actions only
* Max: \$0.01 - Cheap actions only
* Min: $1.00, Max: $5.00 - Mid-range actions

### Filter by date range

Set start and end dates:

* **Start date** - Show actions after this date/time
* **End date** - Show actions before this date/time
* Date picker with time selection
* Timezone-aware

Common presets:

* **Last 24 hours**
* **Last 7 days**
* **Last 30 days**
* **Custom range**

### Full-text search

Search across multiple fields:

* Action name
* Input parameters (JSON content)
* Output results (JSON content)
* Tags
* Agent ID

**Search tips:**

* Use quotes for exact phrases: `"customer email"`
* Searches are case-insensitive
* Matches partial strings

**Examples:**

* Search `error` - Finds actions with "error" in outputs
* Search `user@example.com` - Finds actions with that email
* Search `"payment processed"` - Exact phrase match

### Sort options

Sort by multiple fields:

* **Timestamp** (asc/desc) - Chronological order
* **Cost** (asc/desc) - By expense
* **Duration** (asc/desc) - By execution time
* **Action name** (asc/desc) - Alphabetical

Default: Timestamp descending (newest first).

## Action table

Main table shows all matching actions:

| Column | Description |
| - | - |
| **Timestamp** | When action executed (with timezone) |
| **Action** | Action name |
| **Agent** | Agent ID (link to agent page) |
| **Run** | Run ID (link to run details) |
| **Outcome** | Badge (success/error/blocked/replayed) |
| **Cost** | USD with 4 decimal precision |
| **Duration** | Execution time (ms) |
| **Tags** | Action tags (if any) |

**Badge colors:**

* 🟢 **Success** - Green
* 🔴 **Error** - Red
* 🟠 **Blocked** - Orange
* 🔵 **Replayed** - Blue

**Row actions:**

* Click row to open **Action Inspector**
* Hover for quick preview

## Action inspector modal

Click any action to open detailed view:

### Overview section

* **Action ID** (UUID)
* **Action name**
* **Timestamp** (full precision)
* **Outcome** with description
* **Cost** (USD)
* **Duration** (nanosecond precision, displayed in ms)
* **Agent ID** (link)
* **Run ID** (link)
* **Tags** (if any)

### Inputs section

Full input parameters with:

* **Syntax-highlighted JSON**
* **Expandable/collapsible** nested objects
* **Copy to clipboard** button
* **Type information** (string, number, object, array, etc.)

Example:

```json theme={null}
{
  "prompt": "What is the capital of France?",
  "model": "gpt-4o",
  "max_tokens": 100,
  "temperature": 0.7
}
```

### Outputs section

Full output results with:

* **Syntax-highlighted JSON**
* **Expandable/collapsible** nested objects
* **Copy to clipboard** button
* **Size indicator** (bytes)

Example:

```json theme={null}
{
  "response": "The capital of France is Paris.",
  "tokens_used": 15,
  "finish_reason": "stop"
}
```

### Metadata section

Additional information:

* **Error details** (if outcome=error)
  * Exception type
  * Error message
  * Stack trace (if available)
* **Compliance data** (if applicable)
  * Approval status
  * Approver information
  * Decision rationale
  * Data lineage
  * Model card
* **Original vs Modified** (if downgraded by policy)

### Related actions

Links to related items:

* **Other actions in this run** - View siblings
* **Similar actions** - Same action name, different runs
* **Agent's recent actions** - Last 10 from this agent

## Pagination

Navigate large result sets:

* **Page size**: 50, 100, 500, 1000 per page
* **Page controls**: First, Previous, Next, Last
* **Jump to page**: Enter page number
* **Total count**: Shows total matching actions

> [!NOTE]
>
> Large page sizes (500-1000) may be slower to load. Use filters to reduce result set.

## Export functionality

Click **Export** to download ledger data:

### Export formats

1. **JSONL** (JSON Lines) - One JSON object per line
   * Best for programmatic processing
   * Stream-friendly
   * Newline-delimited

2. **JSON** - Standard JSON array
   * Best for data analysis tools
   * Human-readable
   * Single file

3. **CSV** - Comma-separated values
   * Best for Excel/spreadsheets
   * Flat structure (nested objects flattened)
   * Universal compatibility

### Export options

* **Respects current filters** - Only exports what's visible
* **Includes all fields** - Inputs, outputs, metadata, compliance data
* **Limit**: 100,000 records per export
* **Streaming**: Large exports stream to prevent timeouts

### Export use cases

* **Compliance reporting** - Generate audit reports
* **Cost analysis** - Import into BI tools
* **Data science** - Train models on action patterns
* **Debugging** - Analyze errors in detail
* **Backup** - Archive historical data

## Verify chain integrity

Every ledger row is hash-chained to the one before it and signed with Ed25519.
Click **Verify chain** at the top of the ledger to check your organization's
whole chain:

* **Chain valid**: every row's hash and signature checks out.
* **Chain invalid**: shows the first row (`seq`) where the chain breaks or a
  signature fails, which is where tampering or corruption starts.

The button calls [`GET /api/v1/ledger/verify`](https://docs.agentsentinel.dev/platform/ledger#get-api-v1-ledger-verify).

## Real-time updates

Ledger updates live via WebSocket:

**When new action is logged:**

1. Appears at top of table (if matches filters)
2. Row highlights briefly (fade-in animation)
3. Stats refresh
4. Notification (optional)

**Connection indicator:**

* 🟢 **REALTIME** - Live updates
* 🟡 **POLLING** - Fallback mode (30s refresh)

## Common workflows

### Audit trail for compliance

1. Filter by date range (e.g., last quarter)
2. Export as JSONL
3. Store in compliance archive
4. Generate report showing:
   * All actions logged
   * Human oversight events (approvals)
   * Policy violations (blocked actions)
   * Data lineage

### Find expensive LLM calls

1. Filter by action name: `call_llm`
2. Sort by cost (descending)
3. Review top 10 most expensive
4. Check inputs for optimization opportunities:
   * Reduce max\_tokens?
   * Use cheaper model?
   * Add caching?

### Debug errors for specific agent

1. Filter by agent\_id: `my-agent`
2. Filter by outcome: Error
3. Sort by timestamp (newest first)
4. Open first error in inspector
5. Review error message and stack trace
6. Check inputs that caused error
7. Reproduce and fix

### Track approval decisions

1. In the [gateway decisions timeline](#gateway-decisions-timeline), filter to **Require approval** to see which actions opened approval requests
2. Full-text search: `approved` or `rejected`
3. Filter to actions with compliance metadata
4. Review approver decisions
5. Analyze patterns:
   * Who approves most?
   * What actions get rejected?
   * How long do decisions take?

### Monitor policy enforcement

1. In the [gateway decisions timeline](#gateway-decisions-timeline), filter to **Deny** and read the reason codes
2. Filter the ledger by outcome: Blocked
3. Review what's being blocked
4. If many legitimate actions blocked:
   * Policies may be too strict
   * Adjust in Settings → Policies
5. If many violations:
   * Agent may be misbehaving
   * Review agent logic

## Saved filters (future)

**Coming soon**: Save commonly-used filter combinations:

* "Expensive LLM calls" (action=call\_llm, cost>\$1)
* "Recent errors" (outcome=error, last 24h)
* "High-risk blocks" (outcome=blocked, risk=critical)

Click to apply saved filter instantly.

## Best practices

> [!TIP]
>
> **Use filters liberally**: The ledger can contain millions of actions - always filter to find what you need.

> [!TIP]
>
> **Export regularly for compliance**: Set up monthly exports of all actions for audit trail archival.

> [!WARNING]
>
> **Search is resource-intensive**: Full-text search across millions of records can be slow - combine with date filters for better performance.

> [!TIP]
>
> **Bookmark common searches**: Save frequently-used filter URLs as bookmarks for quick access.

## Keyboard shortcuts

* `/` - Focus search bar
* `f` - Open filter panel
* `e` - Export
* `Esc` - Close inspector modal
* Arrow keys - Navigate table rows

## Troubleshooting

### "No actions showing"

* Check if filters are too restrictive
* Try "Clear all filters" button
* Verify date range includes recent data
* Check if any runs have been created

### "Search not finding results"

* Ensure spelling is correct (case-insensitive but must match)
* Try partial search without quotes
* Check if searching in right field (inputs vs outputs)
* Clear other filters that may exclude results

### "Export timing out"

* Reduce result set with filters
* Try JSONL instead of JSON (streams better)
* Break into multiple exports by date range
* Contact support if exporting > 100k records needed

### "Real-time updates not working"

* Check connection indicator (should be green "REALTIME")
* Refresh page to reconnect WebSocket
* Verify no network/firewall issues
* Fallback polling should activate automatically

## See also

* [Platform Ledger API](https://docs.agentsentinel.dev/platform/ledger.md) - API documentation
* [Runs](https://docs.agentsentinel.dev/console/runs.md) - View actions within specific runs
* [Agents](https://docs.agentsentinel.dev/console/agents.md) - View actions by agent
* [Compliance](https://docs.agentsentinel.dev/platform/compliance.md) - Export compliance reports


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.