Introduction to Audit Logs

Retrieve a record of actions performed in your workspace — who did what, when, and from where.

The Audit Logs API can be used to:

• Feed workspace activity data into your SIEM or other monitoring tools
• Track changes across your organization, from workspace settings and model keys to role changes, failed login attempts, and more
• Build custom dashboards and reports for workspace activity

Prerequisites

To use the Audit Logs API, you need:

• Workspace Admin Permission: Only workspace administrators can create API keys with audit log permissions.
• API Key with AUDIT_LOG_API Scope: Your API key must have the dedicated audit log scope enabled.

Important Security Notice: Users with access to an API key with the AUDIT_LOG_API scope can read all audit log data for the workspace, including IP addresses, user actions, and configuration changes. Only grant this permission to trusted users.

Retention

Audit log entries are retained for 90 days. Make sure to export or forward any data you need before it expires.

Available Endpoint

GET /audit-logs/{workspace_id}

Authentication

All API requests require Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

The Audit Log Entry

Every audit log entry describes an actor taking an action on an entity. Here's what each entry contains:

Field	Description
actor_id, actor_type, actor_name	Who performed the action. Actor types: USER, API_KEY, SYSTEM, SCIM
action	What happened, in dot notation (e.g. user.updated, workspace.created, api_keys.deleted)
entity_type, entity_id	Which resource was affected (e.g. User, Workspace, Group, IntegrationConnection)
created_at	When the event occurred
ip_address, user_agent	Where the request came from
changes	A before/after diff of changed fields (for update events)
snapshot	Full entity snapshot or additional event metadata (e.g. on delete/create events, or extra context like failed login details)

Pagination

The API uses cursor-based pagination. Each response includes a next_cursor field — pass it as the cursor query parameter in your next request to get the following page. When next_cursor is null, you've reached the end.

# First request
curl "https://api.odeus.ai/audit-logs/{workspace_id}?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page
curl "https://api.odeus.ai/audit-logs/{workspace_id}?limit=50&cursor={next_cursor}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filtering

You can narrow results using query parameters:

Parameter	Type	Description
from	datetime	Start of date range (ISO 8601)
to	datetime	End of date range (ISO 8601)
entity_type	string	Filter by entity type (e.g. User, Workspace)
actor_id	uuid	Filter by the actor who performed the action
limit	integer	Items per page (default 50, max 50)
cursor	uuid	Cursor from previous response for pagination

Error Handling

Status Code	Description
400	Invalid request parameters (e.g. malformed date, invalid UUID)
401	Missing or invalid API key
403	API key lacks AUDIT_LOG_API scope, or workspace_id doesn't match
429	Rate limit exceeded — back off and retry
500	Internal server error

Odeus intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.