Audit Activity API

Query SQL Server audit events captured by the kAudit agent. All endpoints require the read:audit-activity scope.

List audit activity events

GET /api/v1/public/audit-activity

Returns a paginated list of audit activity events, ordered by timestamp (newest first by default).

Query parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
pageSize	integer	20	Results per page (max 100)
search	string	—	Full-text search across event fields
sortBy	string	—	Column to sort by (e.g., Timestamp)
sortDirection	string	desc	Sort direction: asc or desc
actionId	string	—	Filter by SQL action code (e.g., SL, IN, LO)
databaseName	string	—	Filter by database name
principalName	string	—	Filter by SQL login / principal name
startTime	ISO 8601	—	Start of time range (e.g., 2026-05-01T00:00:00Z)
endTime	ISO 8601	—	End of time range

Example request

curl "https://api.kovoco.net/api/v1/public/audit-activity?actionId=SL&databaseName=customers_db&pageSize=10" \
  -H "X-Api-Key: your-api-key-here"

Example response

{
  "data": [
    {
      "recordId": "abc123-def456",
      "tenantId": "your-tenant-id",
      "eventTime": "2026-05-03T14:23:01Z",
      "actionId": "SL",
      "succeeded": true,
      "serverInstanceName": "Production SQL 01",
      "databaseName": "customers_db",
      "schemaName": "dbo",
      "objectName": "Orders",
      "serverPrincipalName": "app_service_account",
      "databasePrincipalName": "dbo",
      "applicationName": "MyApp",
      "hostName": "app-server-01",
      "clientIp": "10.0.1.50",
      "sourceType": "SqlAudit",
      "statementPreview": "SELECT TOP 100 * FROM dbo.Orders WHERE ..."
    }
  ],
  "meta": {
    "totalCount": 2483,
    "page": 1,
    "pageSize": 10,
    "totalPages": 249,
    "hasPreviousPage": false,
    "hasNextPage": true,
    "timestamp": "2026-05-03T14:25:00Z",
    "apiVersion": "1.0"
  }
}

Response fields

Field	Type	Description
recordId	string	Unique identifier for this audit event
tenantId	string	The tenant this event belongs to
eventTime	ISO 8601	When the event occurred on the SQL Server
actionId	string	SQL action code (SL, IN, UP, DL, EX, CR, AL, DR, LO, etc.)
succeeded	boolean	Whether the SQL action completed successfully
serverInstanceName	string	The SQL Server instance name
databaseName	string	The database the event occurred on
schemaName	string	The schema of the accessed object
objectName	string	The database object accessed or modified
serverPrincipalName	string	The server-level login that performed the action
databasePrincipalName	string	The database-level principal
applicationName	string	The client application name (if captured)
hostName	string	The client host machine name (if captured)
clientIp	string	The client IP address
sourceType	string	The audit source type
statementPreview	string	A preview of the SQL statement (if captured)

---

Get event by ID

GET /api/v1/public/audit-activity/{recordId}

Returns a single audit activity event with full detail.

Path parameters

Parameter	Description
recordId	The unique record identifier (string)

Example request

curl "https://api.kovoco.net/api/v1/public/audit-activity/abc123-def456" \
  -H "X-Api-Key: your-api-key-here"

Example response

{
  "data": {
    "recordId": "abc123-def456",
    "tenantId": "your-tenant-id",
    "eventTime": "2026-05-03T14:23:01Z",
    "actionId": "SL",
    "succeeded": true,
    "serverInstanceName": "Production SQL 01",
    "databaseName": "customers_db",
    "schemaName": "dbo",
    "objectName": "Orders",
    "serverPrincipalName": "app_service_account",
    "databasePrincipalName": "dbo",
    "applicationName": "MyApp",
    "hostName": "app-server-01",
    "clientIp": "10.0.1.50",
    "statement": "SELECT TOP 100 * FROM dbo.Orders WHERE OrderDate > '2026-01-01'"
  },
  "meta": {
    "timestamp": "2026-05-03T14:25:00Z",
    "apiVersion": "1.0"
  }
}

Error responses

Status	Meaning
404	Record not found within your authorized tenants
400	Invalid record ID format

---

Get activity summary

GET /api/v1/public/audit-activity/summary

Returns aggregate metrics for audit activity across your tenants.

Query parameters

Parameter	Type	Default	Description
startTime	ISO 8601	—	Start of time range
endTime	ISO 8601	—	End of time range (defaults to now)

Example request

curl "https://api.kovoco.net/api/v1/public/audit-activity/summary?startTime=2026-05-01T00:00:00Z" \
  -H "X-Api-Key: your-api-key-here"

Example response

{
  "data": {
    "totalCount": 48291,
    "successfulCount": 47832,
    "failedCount": 459,
    "distinctDatabases": 12,
    "distinctPrincipals": 34,
    "latestEventTime": "2026-05-03T14:23:01Z"
  },
  "meta": {
    "timestamp": "2026-05-03T14:25:00Z",
    "apiVersion": "1.0"
  }
}

Summary fields

Field	Type	Description
totalCount	integer	Total audit events in the time range
successfulCount	integer	Events where the SQL action succeeded
failedCount	integer	Events where the action failed or was denied
distinctDatabases	integer	Number of distinct databases with activity
distinctPrincipals	integer	Number of distinct SQL logins with activity
latestEventTime	ISO 8601	Timestamp of the most recent event

---

Common error responses

All endpoints in this section may return:

Status	Code	Description
401	unauthorized	API key is missing or invalid
403	forbidden	API key does not have the read:audit-activity scope, or no tenant claims
429	rate_limited	Rate limit exceeded — check Retry-After header
503	service_unavailable	The audit activity query service is temporarily offline