Activity Ledger API - Agent Sentinel

The Activity Ledger provides a chronological, filterable view of every action taken by your agents across all runs. This is the compliance substrate, audit evidence, and organizational memory for Agent Sentinel.

Overview

Unlike the /runs endpoints which are hierarchical (Run → Actions), the ledger provides a flat, chronological stream of all actions with advanced filtering and search capabilities.

Key Use Cases

Compliance Audits: “Show me all high-risk actions in Q4 2024”
Debugging: “Find all failed database_query actions”
Cost Analysis: “What are my most expensive actions?”
Security: “Show all actions by prod-agent-3 that were blocked”
Organizational Memory: “What did our agents do last week?”

Endpoints

GET /api/v1/ledger

Query the activity ledger with filtering, sorting, and pagination.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	0	Page number (0-indexed)
`page_size`	integer	100	Items per page (max 1000)
`outcome`	string	null	Filter by outcome: `success`, `error`, `blocked`
`action_name`	string	null	Filter by exact action name
`agent_id`	string	null	Filter by agent identifier
`run_id`	UUID	null	Filter by parent run
`min_cost`	float	null	Minimum cost in USD
`max_cost`	float	null	Maximum cost in USD
`start_date`	ISO 8601	null	Filter actions after this date
`end_date`	ISO 8601	null	Filter actions before this date
`search`	string	null	Search across action names, agent IDs, outcomes
`sort_by`	enum	`timestamp`	Sort field: `timestamp`, `cost`, `duration`, `name`
`sort_order`	enum	`desc`	Sort direction: `asc`, `desc`

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "database_query",
      "outcome": "error",
      "cost_usd": 0.05,
      "duration_ms": 1234.5,
      "inputs": {
        "query": "SELECT * FROM users WHERE id = ?",
        "params": [123]
      },
      "outputs": {
        "error": "Connection timeout"
      },
      "run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "run_status": "failed",
      "agent_id": "prod-agent-3",
      "timestamp": "2024-12-28T10:30:00.123456Z",
      "compliance_metadata": null,
      "organization_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "actor": {
        "type": "agent",
        "id": "prod-agent-3",
        "key_id": "sk_live_ab12",
        "principal": "svc-account",
        "harness": "langchain"
      },
      "counterparty": null
    }
  ],
  "count": 1,
  "page": 0,
  "page_size": 50,
  "total_pages": 1
}

Example: Find Failed Actions

curl -X GET "https://api.agent-sentinel.dev/api/v1/ledger?outcome=error&sort_by=cost&sort_order=desc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example: Search Actions

curl -X GET "https://api.agent-sentinel.dev/api/v1/ledger?search=database&page_size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example: Date Range Query

curl -X GET "https://api.agent-sentinel.dev/api/v1/ledger?start_date=2024-12-01T00:00:00Z&end_date=2024-12-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/v1/ledger/stats

Get aggregate statistics for the activity ledger.

Query Parameters

Parameter	Type	Default	Description
`start_date`	ISO 8601	null	Start date for stats calculation
`end_date`	ISO 8601	null	End date for stats calculation
`agent_id`	string	null	Calculate stats for specific agent

Response

{
  "total_actions": 4200,
  "total_cost_usd": 42.50,
  "success_count": 4120,
  "error_count": 75,
  "blocked_count": 5,
  "average_duration_ms": 234.5,
  "unique_agents": 12,
  "unique_action_types": 45
}

Example: Monthly Stats

curl -X GET "https://api.agent-sentinel.dev/api/v1/ledger/stats?start_date=2024-12-01T00:00:00Z&end_date=2024-12-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/v1/ledger/export

Export ledger data for compliance audits and offline analysis.

Query Parameters

Parameter	Type	Default	Description
`format`	enum	`jsonl`	Export format: `jsonl`, `json`, `csv`
`outcome`	string	null	Filter by outcome
`action_name`	string	null	Filter by action name
`agent_id`	string	null	Filter by agent
`start_date`	ISO 8601	null	Date range start
`end_date`	ISO 8601	null	Date range end
`limit`	integer	10000	Maximum records (max 100,000)

Response

File download in requested format.

Example: Export as JSONL

curl -X GET "https://api.agent-sentinel.dev/api/v1/ledger/export?format=jsonl&limit=1000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o ledger.jsonl

Example: Export Failed Actions as CSV

curl -X GET "https://api.agent-sentinel.dev/api/v1/ledger/export?format=csv&outcome=error" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o failed_actions.csv

GET /api/v1/ledger/verify

Re-derive an organization’s row hash chain from stored data and report whether it’s intact.

Query Parameters

Parameter	Type	Default	Description
`organization_id`	UUID	caller’s active organization	Organization whose chain to verify
`from_seq`	integer	null	First `seq` to check (inclusive)
`to_seq`	integer	null	Last `seq` to check (inclusive)

Non-superusers may only verify their own active organization’s chain; requesting a different organization_id returns 403.

Response

{
  "valid": true,
  "checked": 428,
  "first_bad_seq": null,
  "key_ids": ["default"]
}

If valid is false, first_bad_seq is the earliest seq whose stored row_hash no longer matches what’s recomputed from its current fields and prev_hash — evidence that row (or an earlier one) was altered or deleted after it was chained.

Example

curl -X GET "https://api.agent-sentinel.dev/api/v1/ledger/verify?from_seq=1&to_seq=1000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Hash Chain & Signing

Every ledger row is chained to the previous row written for its organization, and optionally Ed25519-signed:

seq — gap-free, per-organization sequence number. Assigned under a Postgres advisory lock (pg_advisory_xact_lock, keyed by organization) so concurrent ingest batches to the same org can’t race each other into duplicate or gapped values.
prev_hash — the previous row’s row_hash (null for the first row in the chain).
row_hash — sha256 of the row’s immutable fields (everything set at ingest time, excluding compliance_metadata) plus prev_hash.
signature / key_id — Ed25519 signature of row_hash and the signing key used. Both are null until a signing key is configured (COMPLIANCE_SIGNING_KEY_ED25519; see the Compliance Guide). Rows written before a key existed stay permanently unsigned (“pre-signing”) — a later key rollout does not retroactively sign history.
compliance_metadata.log_hash / tamper_seal — mirror row_hash / signature, for tooling that only reads compliance_metadata.

Altering or deleting a historical row breaks the chain from that row forward: every subsequent row’s prev_hash stops matching, and GET /ledger/verify (or the standalone script below) reports the first broken seq.

Verifying from outside the platform

scripts/verify_ledger_chain.py re-derives the same chain directly against a database URL, for auditors who don’t have (or don’t want to rely on) API access to the running platform:

python scripts/verify_ledger_chain.py \
  --database-url postgresql://user:pass@host:5432/agent_sentinel \
  --organization-id 3fa85f64-5717-4562-b3fc-2c963f66afa6

It exits non-zero if the chain is broken, so it can be wired into a cron job or CI as a tamper tripwire.

Response Schema

LedgerEntry

interface LedgerEntry {
  // Core Action Data
  id: string;              // UUID
  name: string;            // Action name (e.g., "send_email", "database_query")
  outcome: string;         // "success", "error", "blocked", etc.
  cost_usd: number;        // Cost in USD
  duration_ms: number;     // Execution duration
  
  // Payload
  inputs: Record<string, any> | null;    // Action inputs/arguments
  outputs: Record<string, any> | null;   // Action outputs/return value
  
  // Context
  run_id: string;          // UUID of parent run
  run_status: string;      // "running", "completed", "failed"
  agent_id: string | null; // Agent identifier
  timestamp: string;       // ISO 8601 timestamp
  
  // Compliance (Enterprise Tier)
  compliance_metadata: ComplianceMetadata | null;
  
  // Organization
  organization_id: string | null;

  // Attribution
  actor: Actor | null;
  counterparty: Counterparty | null;
}

Actor / Counterparty

Every ledger row is self-describing: actor and counterparty record who did what without requiring a join through /runs. This is the same identity shape used across Agent Sentinel’s governance tables (agent id, principal, harness, key id, mandate reference), so it stays compatible with A2A agent cards and AP2/TAP mandate references.

interface Actor {
  type: "user" | "agent" | "service"; // Caller classification
  id: string | null;                  // Agent identifier, if any
  key_id: string | null;              // API key prefix used to authenticate
  principal: string | null;           // Accountable identity (X-Sentinel-Principal), e.g. "user@example.com"
  harness: string | null;             // Agent harness/framework (X-Sentinel-Harness), e.g. "langchain"
}

interface Counterparty {
  type: string;              // e.g. "user", "organization", "agent"
  id: string;                // Counterparty identifier
  mandate_ref: string | null; // AP2/TAP mandate reference, if any
}

actor is derived server-side from the verified API key/JWT plus the SDK’s X-Sentinel-* identity headers — it cannot be spoofed by the request body. counterparty is optional and comes from a counterparty field on the SDK’s ingest entry, for actions performed against or on behalf of another party (e.g. a buyer agent in an AP2 transaction).

ComplianceMetadata (Enterprise Tier)

interface ComplianceMetadata {
  // Human-in-the-Loop (EU AI Act Article 14)
  requires_human_approval?: boolean;
  approval_status?: "not_required" | "pending" | "approved" | "rejected" | "timeout";
  human_in_the_loop_id?: string;
  human_in_the_loop_email?: string;
  approval_timestamp?: string;
  approval_notes?: string;
  
  // Decision Transparency
  decision_rationale?: string;
  confidence_score?: number;
  alternative_actions_considered?: string[];
  
  // Data Lineage
  input_data_sources?: Array<{
    source: string;
    version: string;
    table?: string;
  }>;
  model_card?: {
    name: string;
    version: string;
    provider: string;
    system_prompt_hash?: string;
  };
  
  // Audit Flags
  policy_violations_checked?: string[];
  override_reason?: string;
}

Common Patterns

1. Debugging Failed Actions

import requests

def find_failed_actions(api_key: str, action_name: str):
    """Find all failed instances of a specific action."""
    url = "https://api.agent-sentinel.dev/api/v1/ledger"
    params = {
        "outcome": "error",
        "action_name": action_name,
        "sort_by": "timestamp",
        "sort_order": "desc",
        "page_size": 100,
    }
    headers = {"Authorization": f"Bearer {api_key}"}
    
    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
    
    data = response.json()
    print(f"Found {data['count']} failed {action_name} actions")
    
    for entry in data['data']:
        print(f"[{entry['timestamp']}] {entry['name']} - {entry['outputs']['error']}")
    
    return data['data']

# Usage
failed_queries = find_failed_actions("sk_...", "database_query")

2. Cost Analysis by Agent

def analyze_agent_costs(api_key: str, agent_id: str):
    """Calculate total cost for a specific agent."""
    url = "https://api.agent-sentinel.dev/api/v1/ledger/stats"
    params = {"agent_id": agent_id}
    headers = {"Authorization": f"Bearer {api_key}"}
    
    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
    
    stats = response.json()
    print(f"Agent: {agent_id}")
    print(f"Total Actions: {stats['total_actions']}")
    print(f"Total Cost: ${stats['total_cost_usd']:.2f}")
    print(f"Average Duration: {stats['average_duration_ms']:.0f}ms")
    print(f"Success Rate: {stats['success_count'] / stats['total_actions'] * 100:.1f}%")
    
    return stats

# Usage
stats = analyze_agent_costs("sk_...", "prod-agent-3")

3. Compliance Audit Export

def export_compliance_report(api_key: str, start_date: str, end_date: str):
    """Export all actions for a date range (for compliance audits)."""
    url = "https://api.agent-sentinel.dev/api/v1/ledger/export"
    params = {
        "format": "csv",
        "start_date": start_date,
        "end_date": end_date,
        "limit": 100000,
    }
    headers = {"Authorization": f"Bearer {api_key}"}
    
    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
    
    filename = f"compliance_report_{start_date}_{end_date}.csv"
    with open(filename, "wb") as f:
        f.write(response.content)
    
    print(f"Exported compliance report to {filename}")
    return filename

# Usage
export_compliance_report(
    "sk_...",
    "2024-10-01T00:00:00Z",
    "2024-12-31T23:59:59Z"
)

4. Real-Time Monitoring

import time

def monitor_failures(api_key: str, interval_seconds: int = 60):
    """Monitor for new failures in real-time."""
    url = "https://api.agent-sentinel.dev/api/v1/ledger"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    last_seen_id = None
    
    while True:
        params = {
            "outcome": "error",
            "sort_by": "timestamp",
            "sort_order": "desc",
            "page_size": 10,
        }
        
        response = requests.get(url, params=params, headers=headers)
        response.raise_for_status()
        
        data = response.json()
        new_failures = []
        
        for entry in data['data']:
            if entry['id'] == last_seen_id:
                break
            new_failures.append(entry)
        
        if new_failures:
            last_seen_id = new_failures[0]['id']
            for failure in reversed(new_failures):
                print(f"🚨 NEW FAILURE: {failure['name']} - {failure['outputs'].get('error', 'Unknown error')}")
        
        time.sleep(interval_seconds)

# Usage (runs indefinitely)
monitor_failures("sk_...")

Authentication

All ledger endpoints require authentication via:

JWT Bearer Token

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

API Key (recommended for programmatic access)
Authorization: sk_1234567890abcdef

See Authentication for details.

Access Control

Users can only see actions from their own runs
Superusers can see all actions across all users
Organization admins can see actions from their organization’s runs

Rate Limits

Query Endpoints: 1000 requests/hour
Export Endpoint: 100 requests/hour
Stats Endpoint: 600 requests/hour

For higher limits, contact support at hello@agentsentinel.dev.

Differences from /runs Endpoints

Feature	`/runs`	`/ledger`
Structure	Hierarchical (Run → Actions)	Flat (all actions)
Scope	Single run at a time	All runs combined
Filtering	By run properties	By action properties
Use Case	Inspect specific run	Audit trail, search
Sorting	Actions within run	Cross-run sorting

When to use /runs:

Inspecting a specific run’s execution flow
Debugging a single agent workflow
Viewing run-level metadata

When to use /ledger:

Compliance audits across all activity
Finding patterns across multiple runs
Cost analysis by action type
Security monitoring

Best Practices

1. Use Pagination for Large Results

# DON'T: Fetch all 10,000 actions at once
response = requests.get("/api/v1/ledger?page_size=10000")

# DO: Paginate through results
page = 0
while True:
    response = requests.get(f"/api/v1/ledger?page={page}&page_size=100")
    data = response.json()
    process_entries(data['data'])
    
    if page >= data['total_pages'] - 1:
        break
    page += 1

2. Use Search for Flexible Queries

# Instead of exact matching:
response = requests.get("/api/v1/ledger?action_name=database_query")

# Use search for partial matches:
response = requests.get("/api/v1/ledger?search=database")

3. Filter by Date Range for Performance

# DON'T: Query all historical data
response = requests.get("/api/v1/ledger")

# DO: Limit to relevant time window
response = requests.get("/api/v1/ledger?start_date=2024-12-01T00:00:00Z&end_date=2024-12-31T23:59:59Z")

4. Use Stats Endpoint for Aggregates

# DON'T: Fetch all actions and calculate manually
actions = requests.get("/api/v1/ledger?page_size=10000").json()
total_cost = sum(a['cost_usd'] for a in actions['data'])

# DO: Use stats endpoint
stats = requests.get("/api/v1/ledger/stats").json()
total_cost = stats['total_cost_usd']

Troubleshooting

Empty Results

Problem: Query returns 0 results Solutions:

Check filters - they may be too restrictive
Verify date range includes expected data
Ensure authentication is correct (not seeing another user’s data)
Check that agents have actually executed actions

Slow Queries

Problem: Queries take >5 seconds Solutions:

Reduce page size (100 instead of 1000)
Add date range filters to limit data scanned
Avoid search queries on large datasets
Use stats endpoint for aggregates instead of fetching all data

Export Limits

Problem: “Export limit exceeded” error Solutions:

Reduce date range or add more filters
Export in batches using pagination
Contact support for bulk export access

Runs API - Hierarchical run/action queries
Ingest API - How SDK sends action data
Authentication - API keys and JWT tokens
Compliance Guide - Enterprise compliance features

Feedback

Have suggestions for the ledger API? Open an issue on the SDK repo or reach out to support.

​Overview

​Key Use Cases

​Endpoints

​GET /api/v1/ledger

​Query Parameters

​Response

​Example: Find Failed Actions

​Example: Search Actions

​Example: Date Range Query

​GET /api/v1/ledger/stats

​Query Parameters

​Response

​Example: Monthly Stats

​GET /api/v1/ledger/export

​Query Parameters

​Response

​Example: Export as JSONL

​Example: Export Failed Actions as CSV

​GET /api/v1/ledger/verify

​Query Parameters

​Response

​Example

​Hash Chain & Signing

​Verifying from outside the platform

​Response Schema

​LedgerEntry

​Actor / Counterparty

​ComplianceMetadata (Enterprise Tier)

​Common Patterns

​1. Debugging Failed Actions

​2. Cost Analysis by Agent

​3. Compliance Audit Export

​4. Real-Time Monitoring

​Authentication

​Access Control

​Rate Limits

​Differences from /runs Endpoints

​Best Practices

​1. Use Pagination for Large Results

​2. Use Search for Flexible Queries

​3. Filter by Date Range for Performance

​4. Use Stats Endpoint for Aggregates

​Troubleshooting

​Empty Results

​Slow Queries

​Export Limits

​Related Documentation

​Feedback

Overview

Key Use Cases

Endpoints

GET /api/v1/ledger

Query Parameters

Response

Example: Find Failed Actions

Example: Search Actions

Example: Date Range Query

GET /api/v1/ledger/stats

Query Parameters

Response

Example: Monthly Stats

GET /api/v1/ledger/export

Query Parameters

Response

Example: Export as JSONL

Example: Export Failed Actions as CSV

GET /api/v1/ledger/verify

Query Parameters

Response

Example

Hash Chain & Signing

Verifying from outside the platform

Response Schema

LedgerEntry

Actor / Counterparty

ComplianceMetadata (Enterprise Tier)

Common Patterns

1. Debugging Failed Actions

2. Cost Analysis by Agent

3. Compliance Audit Export

4. Real-Time Monitoring

Authentication

Access Control

Rate Limits

Differences from /runs Endpoints

Best Practices

1. Use Pagination for Large Results

2. Use Search for Flexible Queries

3. Filter by Date Range for Performance

4. Use Stats Endpoint for Aggregates

Troubleshooting

Empty Results

Slow Queries

Export Limits

Related Documentation

Feedback