Query Audit Logs

Page Outline

• Path Parameters
• Query Parameters
• Action Types
• Behavior
• Response

---

Retrieves structured audit log entries for a model, recording all significant lifecycle events, configuration changes, and access actions performed by users and automated systems.

Base Path: /api/v1/models

Method: GET

Path: /{model_id}/audit-logs

Auth: Requires a valid Bearer token (Authorization: Bearer <JWT>)

Path Parameters

Parameter	Type	Description
model_id	string	Unique identifier of the model

Query Parameters

Parameter	Type	Default	Description
from	string (ISO 8601)	90 days ago	Start of the audit log window
to	string (ISO 8601)	now	End of the audit log window
action	string	—	Filter by action type (see Action Types below)
actor_id	string	—	Filter to events performed by a specific user ID
page	integer	1	Page number
page_size	integer	50	Results per page (max: 200)
sort_order	string	desc	Chronological order: asc or desc

Action Types

The action filter supports any of the following audit event types:

Action	Description
model.created	Model record was created
model.updated	Metadata or config was modified
model.deleted	Model was permanently deleted
model.archived	Model was archived
model.unarchived	Model was restored from archive
model.duplicated	A copy of the model was created
model.training_started	A training run was initiated
model.training_completed	A training run completed successfully
model.training_failed	A training run failed
model.version_promoted	A version was set as the promoted version
model.version_restored	A version was restored as the config baseline
model.dataset_linked	A dataset was linked to the model
model.dataset_unlinked	The dataset link was removed
model.config_updated	Training configuration was updated
model.settings_updated	Display/notification/access settings were modified
model.collaborator_added	A user was granted access
model.collaborator_removed	A user's access was revoked

Behavior

• Audit logs are immutable — they cannot be deleted or modified via the API.
• Logs older than the organization's retention policy (default: 365 days) may not be returned.
• The metadata field contains event-specific context (e.g., changed field names and previous values).
• Requires the caller to have admin or owner role on the model to access audit logs.
• Returns HTTP 404 if the model is not found; HTTP 403 if the caller lacks audit access.

Response

Returns a paginated AuditLogList object.

{
  "total": 87,
  "page": 1,
  "page_size": 50,
  "logs": [
    {
      "log_id": "log-00142",
      "action": "model.version_promoted",
      "model_id": "mdl-7f3a19bc",
      "actor": {
        "user_id": "user-001",
        "email": "alice@example.com",
        "ip_address": "192.168.1.42"
      },
      "metadata": {
        "previous_version_id": "ver-000",
        "new_version_id": "ver-001"
      },
      "timestamp": "2026-03-13T16:10:00Z"
    }
  ]
}