Overview The log endpoint records all actions your agents attempt or complete. This creates a comprehensive audit trail for compliance, debugging, and analytics.
Authentication Your organization’s API key
Request Body Unique identifier of the agent that performed the action
The action identifier (e.g., “stripe.refund”, “email.send”)
Status of the action: "success", "failed", "pending", or "denied"
Additional details about the action (amounts, IDs, error messages, etc.)
IP address where the action originated
Example Request cURL
Python
JavaScript
Go
Ruby
curl -X POST https://api.agentwarden.io/sdk/log \ -H "X-API-Key: ak_1234567890abcdefghij" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "550e8400-e29b-41d4-a716-446655440000", "action": "stripe.refund", "status": "success", "context": { "amount": 50.00, "customer_id": "cus_ABC123", "refund_id": "re_xyz789", "reason": "defective_product" }, "ip_address": "192.168.1.100" }'
Response Unique identifier for the log entry (UUID)
The agent that performed the action
The action that was logged
Status of the action (success, failed, pending, denied)
Additional context provided
Timestamp when the log was created (ISO 8601)
Success Response { "id" : "log_abc123xyz789" , "agent_id" : "550e8400-e29b-41d4-a716-446655440000" , "organization_id" : "org_def456ghi012" , "action" : "stripe.refund" , "status" : "success" , "context" : { "amount" : 50.00 , "customer_id" : "cus_ABC123" , "refund_id" : "re_xyz789" , "reason" : "defective_product" }, "created_at" : "2024-02-21T10:30:00Z" }
Status Values Action completed successfully
Action failed due to an error
Action is waiting (e.g., for approval or async completion)
Action was blocked by permission check
Logging Patterns Pattern 1: Success { "agent_id" : "support-bot" , "action" : "stripe.refund" , "status" : "success" , "context" : { "amount" : 50.00 , "refund_id" : "re_xyz789" , "processing_time_ms" : 234 } }
Pattern 2: Failure Include error details in context:
{ "agent_id" : "support-bot" , "action" : "stripe.refund" , "status" : "failed" , "context" : { "amount" : 50.00 , "error" : "insufficient_funds" , "error_message" : "Customer has insufficient funds" , "stripe_error_code" : "card_declined" } }
Pattern 3: Denied Log when permission check blocks an action:
{ "agent_id" : "support-bot" , "action" : "stripe.refund" , "status" : "denied" , "context" : { "amount" : 150.00 , "reason" : "Amount exceeds maximum allowed 100.00" } }
Pattern 4: Pending Approval { "agent_id" : "devops-bot" , "action" : "deploy.production" , "status" : "pending" , "context" : { "version" : "v2.1.0" , "approval_id" : "apr_abc123" , "requires_approval" : true } }
Plan Limits Logging is subject to monthly limits based on your plan:
Plan Logs per Month Retention Free 1,000 7 days Pro 50,000 30 days Business 500,000 90 days Enterprise Unlimited Custom
Exceeding Limits If you exceed your monthly log limit:
HTTP Status: 403 Forbidden{ "detail" : { "error" : "plan_limit_exceeded" , "message" : "Monthly log limit reached (1000/1000). Upgrade your plan for more logs." , "limit_type" : "logs" , "current_plan" : "free" , "upgrade_url" : "/settings?tab=plans" } }
Error Responses 401 Unauthorized Invalid or missing API key:
{ "detail" : "Invalid API key" }
400 Bad Request Missing required fields:
{ "detail" : { "agent_id" : [ "This field is required" ], "action" : [ "This field is required" ], "status" : [ "This field is required" ] } }
Invalid status value:
{ "detail" : { "status" : [ "Must be one of: success, failed, pending, denied" ] } }
404 Not Found Agent doesn’t exist:
{ "detail" : "Agent not found" }
403 Forbidden Monthly log limit exceeded (see Plan Limits section above).
Best Practices
1. Always Log After Actions
Log every action your agent performs, whether successful or not: try : result = execute_action() guard.log(agent_id, action, "success" , result) except Exception as e: guard.log(agent_id, action, "failed" , { "error" : str (e)})
The more context, the better for debugging and audits: # ✅ Good - detailed context context = { "amount" : 50.00 , "customer_id" : "cus_123" , "refund_id" : "re_xyz" , "processing_time_ms" : 234 , "api_version" : "2023-10-16" , "idempotency_key" : "idem_abc" } # ❌ Bad - minimal context context = { "amount" : 50.00 }
Even if permission was denied, log it: result = guard.check(agent_id, action, context) if not result.allowed: guard.log( agent_id, action, "denied" , { "reason" : result.reason} )
Add execution time for performance monitoring: import time start = time.time() execute_action() duration = time.time() - start guard.log( agent_id, action, "success" , { "duration_ms" : int (duration * 1000 )} )
5. Structure Error Context
For failures, include structured error information: try : execute_action() except StripeError as e: guard.log( agent_id, action, "failed" , { "error_type" : type (e). __name__ , "error_code" : e.code, "error_message" : str (e), "stripe_request_id" : e.request_id } )
Common Use Cases Successful Action curl -X POST https://api.agentwarden.io/sdk/log \ -H "X-API-Key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "email-bot", "action": "email.send", "status": "success", "context": { "recipient": "customer@example.com", "template": "order_confirmation", "message_id": "msg_abc123" } }'
Failed Action with Error curl -X POST https://api.agentwarden.io/sdk/log \ -H "X-API-Key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "payment-bot", "action": "stripe.charge", "status": "failed", "context": { "amount": 99.00, "customer_id": "cus_123", "error": "card_declined", "error_message": "Your card was declined" } }'
Denied Permission curl -X POST https://api.agentwarden.io/sdk/log \ -H "X-API-Key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "support-bot", "action": "user.delete", "status": "denied", "context": { "user_id": "usr_456", "reason": "No permission found for action user.delete" } }'
Idempotency To prevent duplicate logs from retries, use idempotency keys:
curl -X POST https://api.agentwarden.io/sdk/log \ -H "X-API-Key: YOUR_KEY" \ -H "Idempotency-Key: unique-key-123" \ -H "Content-Type: application/json" \ -d '{ ... }'
If you retry with the same idempotency key within 24 hours, you’ll get the same response without creating a duplicate log.
Rate Limiting This endpoint shares the same rate limits as /sdk/check:
Rate limits by plan:
Free: 100 requests/minute
Pro: 1,000 requests/minute
Business: 10,000 requests/minute
Enterprise: Custom
Viewing Logs Logs can be viewed in:
Dashboard : Visit app.agentwarden.io/logs API : Use the management API to retrieve logs programmaticallyExports : Download CSV exports (Business+ plans)
