auditledge-python

Official Python SDK for Auditledge — the audit log API for SaaS developers.

Add "who did what and when" to your app in minutes.

Install

pip install auditledge

Quickstart

from auditledge import AuditLedge

client = AuditLedge('your_api_key')

# Log an event
client.log({
    'actor': {'id': 'user_123', 'name': 'Alice', 'email': 'alice@example.com'},
    'action': 'invoice.deleted',
    'resource': {'type': 'invoice', 'id': 'inv_456', 'name': 'Invoice #1042'},
    'organization_id': 'org_789',
    'metadata': {'ip': '192.168.1.1'}
})

# Query events
result = client.query({
    'organization_id': 'org_789',
    'limit': 50
})
print(result['events'])   # list of events
print(result['total'])    # total matching count

# Query with filters
result = client.query({
    'actor_id': 'user_123',
    'action': 'invoice',        # partial match
    'start_date': '2026-01-01T00:00:00Z',
    'end_date': '2026-12-31T23:59:59Z',
})

# Export as CSV
csv_data = client.export({'format': 'csv', 'organization_id': 'org_789'})

# Export as JSON
events = client.export({'format': 'json', 'organization_id': 'org_789'})

# Check quota usage
info = client.usage()
print(info['plan'])              # 'free', 'starter', or 'growth'
print(info['events_this_month']) # events logged this month
print(info['events_limit'])      # monthly cap

Django / FastAPI Example

from auditledge import AuditLedge

audit = AuditLedge('your_api_key')

def delete_invoice(request, invoice_id):
    invoice = Invoice.objects.get(id=invoice_id)
    invoice.delete()

    audit.log({
        'actor': {'id': str(request.user.id), 'name': request.user.get_full_name()},
        'action': 'invoice.deleted',
        'resource': {'type': 'invoice', 'id': str(invoice_id)},
        'organization_id': str(request.user.organization_id),
        'metadata': {'ip': request.META.get('REMOTE_ADDR')}
    })

Reference

AuditLedge(api_key, base_url=None, timeout=30)

log(event) → dict

Log an audit event. All fields marked required will raise AuditLedgeError locally before the request is made.

query(filters) → dict

Returns { events: [...], total: int, limit: int, offset: int }.

get(event_id) → dict

Fetch a single event by ID.

export(options) → str or list

Returns a str for CSV, or a list of event dicts for JSON.

usage() → dict

Returns { plan, events_this_month, events_limit, retention_days }.

Links

• 🌐 Website: auditledge.com
• 📖 Docs: docs.auditledge.com
• 🐛 Issues: github.com/auditledge/auditledge-python/issues

License

MIT