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

Twenty-four distinct actions are emitted across thirteen mutation routes. Severity in the dashboard is inferred from the verb (.delete / .rotate / billing.* / workspace.* are HIGH, .create / .update / .invite are MED, the rest are LOW). Every row carries the actor user id and IP address pulled from x-forwarded-for / x-real-ip / cf-connecting-ip.

View the log in Settings → Audit log (admin-only full viewer with time-window + action filters, paginated 50 per page, click any row to open a drawer with the metadata JSON, IP, and actor UUID). Editors and viewers see the abbreviated table on the same Settings tab. Programmatic consumers should hit the REST API below.

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>

# Filter by inclusive time range (ISO 8601)
GET /api/v1/audit-logs?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z

# List the distinct action values seen on this workspace
# (powers the filter dropdown; capped at the last 1000 rows)
GET /api/v1/audit-logs/actions

Query parameters

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
}

Response fields

curl examples

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

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

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

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. Audit logs are retained for the lifetime of your account and are not currently pruned on a fixed schedule. If you need a guaranteed retention window for compliance reasons, export the log periodically via the API and store it in your own system; a future release may introduce per-plan retention windows, at which point this page and the Privacy Policy will be updated together.
• 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.