Audit Logs

Spanlens records every significant action within your organization. Track who changed what and when — API key creation, provider key additions, member invitations, role changes, and plan switches. View the log directly in Settings → Audit log or query it via the REST API to feed into an external SIEM or compliance tool.

Use cases

Security audits. Determine which keys a departing employee created, or whether admin roles changed at an unexpected time.
Compliance. Satisfy SOC 2, ISO 27001, and similar audit requirements that ask for a change access log on demand.
Incident investigation. If the proxy starts returning auth errors, check the audit log for provider key rotations around that time.

Recorded events

action	Description
`api_key.create`	New Spanlens API key (`sl_live_*`) issued
`api_key.delete`	API key revoked
`provider_key.add`	OpenAI / Anthropic / Gemini provider key registered
`provider_key.delete`	Provider key removed
`member.invite`	Team member invitation sent
`member.role_change`	Member role updated (admin / editor / viewer)
`member.remove`	Member removed from the organization
`billing.plan.change`	Plan upgraded or downgraded
`org.settings.update`	Organization name, security settings, or other org-level config changed

API reference

List logs

GET /api/v1/audit-logs?limit=50&offset=0

# Filter by action
GET /api/v1/audit-logs?limit=50&offset=0&action=api_key.create

# Filter by user
GET /api/v1/audit-logs?limit=50&offset=0&user_id=<uuid>

bash

Query parameters

Parameter	Default	Description
`limit`	50	Results per page. Maximum 200.
`offset`	0	Pagination offset.
`action`	(all)	Filter to a specific action value, e.g. `member.invite`.
`user_id`	(all)	Show only actions performed by a specific user.

Response example

{
  "data": [
    {
      "id": "al_01j9abc...",
      "action": "api_key.create",
      "resource_type": "api_key",
      "resource_id": "key_01j9...",
      "user_id": "usr_01j9...",
      "metadata": {
        "key_name": "Production proxy key"
      },
      "ip_address": "203.0.113.42",
      "created_at": "2026-05-15T08:30:00Z"
    },
    {
      "id": "al_01j9def...",
      "action": "member.role_change",
      "resource_type": "org_member",
      "resource_id": "usr_01j9yyy...",
      "user_id": "usr_01j9xxx...",
      "metadata": {
        "from_role": "viewer",
        "to_role": "editor",
        "target_email": "colleague@example.com"
      },
      "ip_address": "198.51.100.7",
      "created_at": "2026-05-15T07:12:45Z"
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

json

Response fields

Field	Type	Description
`id`	string	Unique log entry ID
`action`	string	Action performed (see event table above)
`resource_type`	string	Type of resource changed (e.g. `api_key`, `org_member`)
`resource_id`	string	ID of the changed resource
`user_id`	string	ID of the user who performed the action
`metadata`	object	Event-specific detail (before/after values, target email, etc.)
`ip_address`	string	IP address of the request
`created_at`	string (ISO 8601)	When the event occurred (UTC)

curl examples

# Fetch the 20 most recent entries
curl "https://spanlens-server.vercel.app/api/v1/audit-logs?limit=20" \
  -H "Authorization: Bearer <JWT>"

# Filter to provider key events only
curl "https://spanlens-server.vercel.app/api/v1/audit-logs?action=provider_key.add&limit=50" \
  -H "Authorization: Bearer <JWT>"

# Second page (entries 51–100)
curl "https://spanlens-server.vercel.app/api/v1/audit-logs?limit=50&offset=50" \
  -H "Authorization: Bearer <JWT>"

bash

Limitations

Admin-only access. Only organization members with the admin role can query audit logs. Editors and viewers are blocked in both the API and the dashboard.
200 rows per page maximum. Passing a limit above 200 returns a 400 error.
Fixed sort order. Results are always returned in created_at DESC order. Sort direction cannot be changed.
Retention. Free plan: 30 days. Pro and above: 1 year. For longer retention, export the log periodically via the API and store it externally.
Proxy requests are not recorded here. LLM request and response history is in Requests and Traces. Audit logs focus on organization configuration changes.

Related: Members & Invitations, Security (PII / prompt injection scanning), Webhooks (HTTP event delivery). Dashboard: Settings → Audit log.