Audit Logs

Immutable audit trail for compliance — query logs, filter by action/result, and aggregate stats.

GET/api/v1/audit/logsQuery audit logsBearer Token▾

Returns a paginated, filterable list of audit log entries for an team. Requires the audit:read permission.

Parameters

Name	Type	Required	Description
`userId`	string	Optional	Filter logs by the user who performed the action.e.g. `usr_01hx9z1q2w3e4r5t6y7u`
`action`	string	Optional	Filter logs by action type (e.g. user.login, user.created).e.g. `user.login`
`result`	string	Optional	Filter logs by outcome of the action.e.g. `SUCCESS` `SUCCESSFAILUREDENIED`
`startDate`	string (ISO 8601)	Optional	Start of the date range filter (inclusive).e.g. `2024-01-01T00:00:00Z`
`endDate`	string (ISO 8601)	Optional	End of the date range filter (inclusive).e.g. `2024-12-31T23:59:59Z`
`page`	number	Optional	Page number for pagination (1-indexed). Defaults to 1.e.g. `1`
`limit`	number	Optional	Number of results per page. Defaults to 50, maximum 100.e.g. `50`

Response Fields

Name	Type	Required	Description
`data`	AuditLog[]	Optional	Array of audit log entries for the current page.
`data[].id`	string	Optional	Unique identifier of the audit log entry.
`data[].teamId`	string	Optional	Team the event belongs to.
`data[].userId`	string	Optional	ID of the user who performed the action.
`data[].agentId`	string	Optional	ID of the agent/service that performed the action (if applicable).
`data[].action`	string	Optional	Action that was performed (e.g. user.login).
`data[].resource`	string	Optional	Resource that was acted upon.
`data[].result`	string	Optional	Outcome of the action: SUCCESS, FAILURE, or DENIED.
`data[].metadata`	object	Optional	Arbitrary JSON metadata associated with the event.
`data[].riskScore`	number	Optional	Computed risk score for the event (0–100).
`data[].ipAddress`	string	Optional	IP address from which the action originated.
`data[].userAgent`	string	Optional	User-Agent string of the client.
`data[].createdAt`	string	Optional	ISO 8601 timestamp of when the event occurred.
`total`	number	Optional	Total number of log entries matching the query.
`page`	number	Optional	Current page number.
`limit`	number	Optional	Number of results per page.

Response Example

{
  "data": [
    {
      "id": "aud_01hx9z1q2w3e4r5t6y7u",
      "teamId": "org_01hx9z1q2w3e4r5t6y7u",
      "userId": "usr_01hx9z1q2w3e4r5t6y7u",
      "agentId": null,
      "action": "user.login",
      "resource": "auth",
      "result": "SUCCESS",
      "metadata": {
        "method": "magic_link"
      },
      "riskScore": 5,
      "ipAddress": "203.0.113.42",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "createdAt": "2024-06-01T09:30:00Z"
    }
  ],
  "total": 1240,
  "page": 1,
  "limit": 50
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/audit/logs?result=SUCCESS&page=1&limit=50" \
  -H "Authorization: Bearer <your_token>"

GET/api/v1/audit/statsGet audit statsBearer Token▾

Returns aggregated audit statistics for an team over a configurable time window. Requires the audit:read permission.

Parameters

Name	Type	Required	Description
`days`	number	Optional	Number of past days to include in the stats window. Defaults to 30.e.g. `30`

Response Fields

Name	Type	Required	Description
`totalEvents`	number	Optional	Total number of audit events in the time window.
`byAction`	Array<{ action: string; count: number }>	Optional	Event counts grouped by action type.
`byResult`	Array<{ result: string; count: number }>	Optional	Event counts grouped by result (SUCCESS, FAILURE, DENIED).

Response Example

{
  "totalEvents": 4823,
  "byAction": [
    {
      "action": "user.login",
      "count": 3102
    },
    {
      "action": "user.created",
      "count": 87
    },
    {
      "action": "policy.evaluated",
      "count": 1634
    }
  ],
  "byResult": [
    {
      "result": "SUCCESS",
      "count": 4601
    },
    {
      "result": "FAILURE",
      "count": 158
    },
    {
      "result": "DENIED",
      "count": 64
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/audit/stats?days=30" \
  -H "Authorization: Bearer <your_token>"