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 "$AGENT_SENTINEL_URL/api/v1/ledger?outcome=error&sort_by=cost&sort_order=desc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example: Search Actions

curl -X GET "$AGENT_SENTINEL_URL/api/v1/ledger?search=database&page_size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example: Date Range Query

curl -X GET "$AGENT_SENTINEL_URL/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 "$AGENT_SENTINEL_URL/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 "$AGENT_SENTINEL_URL/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 "$AGENT_SENTINEL_URL/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"],
  "signatures_checked": 428,
  "first_bad_signature_seq": null,
  "head_seq": 428,
  "head_matches": true
}

valid is true only when every check passes. 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. signatures_checked counts the signed rows whose Ed25519 signature was verified against the platform public key (unsigned pre-signing rows are skipped), and first_bad_signature_seq is the earliest signed row whose signature does not verify over its stored row_hash. head_seq is where the organization’s signed ledger head says the chain ends, and head_matches is false when the chain’s last row isn’t that head (rows were deleted from the end), the head is missing, or the head’s signature doesn’t verify. Both are null for a ranged check (to_seq given), which stops before the tail by design and does not consult the head. See Integrity vs. authenticity.

Example

curl -X GET "$AGENT_SENTINEL_URL/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. Concurrent ingest batches to the same organization can’t produce 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. Rows written before signing was enabled stay permanently unsigned (“pre-signing”, null) — enabling signing does not retroactively sign history. See Compliance.
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 reports the first broken seq. Deleting the newest rows leaves the remaining chain intact, so the platform also keeps a signed ledger head, described below.

Ledger head

The platform records each organization’s chain head (the last seq and its row_hash) separately from the chain and signs it. A full verification (no to_seq) compares the chain’s last row with the head and reports the result as head_seq and head_matches. The chain is reported invalid when:

rows were removed from the end, so the last row no longer matches the head;
the chain has rows but no head;
the head is unsigned or its signature does not verify.

This makes truncating the newest rows detectable, not just editing or deleting rows in the middle.

Integrity vs. authenticity

Verification makes two independent guarantees, reported separately:

Chain integrity (first_bad_seq) — no row was altered or removed without breaking the links. This needs no key: anyone can recompute the hashes.
Authenticity (first_bad_signature_seq) — the platform key signed each stored row_hash. Because the hash chain alone is recomputable, someone with database access could edit a row and re-hash it (and every later row) so the chain still links up. They cannot re-sign those hashes without the private key, so the signature check catches the edit even when the chain is intact.

valid is true only when both pass. Pre-signing rows (signature: null) are skipped by the signature check, not failed — they verify on the chain alone, and signatures_checked counts only signed rows. Only null marks a pre-signing row: any non-null signature, including an empty string, is verified and fails if it does not match. Signed rows cannot be authenticated without the public key: if the platform has no key to verify against, every signed row is reported as bad rather than silently passed.

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 = f"{AGENT_SENTINEL_URL}/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 = f"{AGENT_SENTINEL_URL}/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 = f"{AGENT_SENTINEL_URL}/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 = f"{AGENT_SENTINEL_URL}/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 - 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

Ledger head

Integrity vs. authenticity

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