Export Audit Logs

​

GET /api/audit/export

​

Authentication

Authorization: Bearer fn_sess_...

​

Query Parameters

​

Response

• id - Unique entry ID
• timestamp - Unix timestamp in milliseconds
• intent_type - Type of intent (currently always api_call)
• service - Service name
• action - HTTP method and path
• decision - Policy decision (approved or denied)
• reason - Denial reason (empty for approved requests)
• cost_usd - Cost in USD (8 decimal places, empty if N/A)
• policy_version_hash - Hex-encoded Keccak256 hash of policy config
• intent_hash - Hex-encoded Keccak256 hash of request intent
• permit_hash - Reserved for on-chain permits (currently empty)
• merkle_root - Hex-encoded Merkle root for integrity verification

​

Response Headers

Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="audit-log-20260303.csv"
X-Export-Row-Limit: 100000
X-Export-Truncated: false

​

Export Limits

• Maximum rows per export: 100,000
• Entries are ordered by ID descending (newest first)
• If the result exceeds 100,000 rows, X-Export-Truncated: true is set
• Use timestamp filters (from, to) to export data in batches

​

CSV Format Details

• Formula injection protection: Cells starting with =, +, -, @, tab, or carriage return are prefixed with '
• Escaping: Cells containing commas, quotes, or newlines are quoted and internal quotes are doubled
• Numeric precision: cost_usd is formatted with 8 decimal places when present
• Empty values: Null fields are represented as empty strings

​

Examples

curl -X GET "http://localhost:3080/api/audit/export?service=openai&from=1709424000000" \
  -H "Authorization: Bearer fn_sess_YOUR_TOKEN" \
  -o audit-log.csv

​

Example CSV Output

id,timestamp,intent_type,service,action,decision,reason,cost_usd,policy_version_hash,intent_hash,permit_hash,merkle_root
42,1709510400000,api_call,openai,POST /v1/chat/completions,approved,,0.00012300,a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456,1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef,,fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321
41,1709510395000,api_call,binance,POST /api/v3/order,denied,"order value $150.00 exceeds max_order_value_usd $100.00",,b2c3d4e5f6a789012345678901234567890abcdef1234567890abcdef1234567,234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12,,edcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321f

​

Error Responses

{"error": "unauthorized"}

{"error": "database error: ..."}

​

Use Cases

• Compliance auditing: Export complete audit trails for regulatory compliance
• Cost analysis: Import into Excel/Google Sheets to analyze API costs over time
• Security investigation: Export denied requests to identify potential security threats
• Data archival: Regular exports for long-term storage and backup
• Custom reporting: Import into BI tools for custom dashboards and visualizations

​

Best Practices

1. Batch exports: For large datasets, use from and to timestamps to export in batches
2. Monitor truncation: Check X-Export-Truncated header to detect when exports are limited
3. Automate backups: Schedule regular exports to maintain off-site audit log backups
4. Filter strategically: Use service and decision filters to reduce export size