Skip to main content

​
Overview

The Audit Log API provides activity tracking capabilities, allowing you to create and retrieve logs of user actions. Logs are automatically cleaned up after 7 days and support pagination and filtering.

​
Configuration

​
Endpoints

​
Create Audit Log Entry

​
POST /api/audit-log
endpoint
Creates a new audit log entry for the authenticated user.
Authentication: Required Request Body 
curl -X POST https://your-domain.com/api/audit-log \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "created",
    "itemType": "chore",
    "itemName": "Vacuum living room"
  }'
Response
​
id
string
Unique log entry ID
​
userId
string
Clerk user ID who performed the action
​
userName
string
Display name of the user (from Clerk firstName)
​
action
string
The action performed
​
itemType
string
Type of item affected
​
itemName
string
Name of the item
​
createdAt
string
ISO 8601 timestamp when the log was created
Example Response 
{
  "id": "clxlog1",
  "userId": "user_abc123",
  "userName": "John",
  "action": "created",
  "itemType": "chore",
  "itemName": "Vacuum living room",
  "createdAt": "2024-03-15T14:30:00.000Z"
}

​
Get Audit Logs

​
GET /api/audit-log
endpoint
Retrieves audit logs with optional pagination and filtering.
Authentication: Not required (but recommended for production) Query Parameters 
curl -X GET "https://your-domain.com/api/audit-log?page=1"
Response (Paginated)
​
logs
array
Array of log entry objects
​
total
number
Total number of logs matching the filters
Example Response (Paginated) 
{
  "logs": [
    {
      "id": "clxlog5",
      "userId": "user_abc123",
      "userName": "John",
      "action": "deleted",
      "itemType": "bill",
      "itemName": "Electric Bill",
      "createdAt": "2024-03-15T16:00:00.000Z"
    },
    {
      "id": "clxlog4",
      "userId": "user_xyz789",
      "userName": "Sarah",
      "action": "created",
      "itemType": "shopping",
      "itemName": "Milk",
      "createdAt": "2024-03-15T15:30:00.000Z"
    },
    {
      "id": "clxlog3",
      "userId": "user_abc123",
      "userName": "John",
      "action": "updated",
      "itemType": "chore",
      "itemName": "Vacuum living room",
      "createdAt": "2024-03-15T15:00:00.000Z"
    },
    {
      "id": "clxlog2",
      "userId": "user_xyz789",
      "userName": "Sarah",
      "action": "created",
      "itemType": "maintenance",
      "itemName": "Replace air filter",
      "createdAt": "2024-03-15T14:45:00.000Z"
    },
    {
      "id": "clxlog1",
      "userId": "user_abc123",
      "userName": "John",
      "action": "created",
      "itemType": "chore",
      "itemName": "Vacuum living room",
      "createdAt": "2024-03-15T14:30:00.000Z"
    }
  ],
  "total": 23
}
Response (All Logs) 
{
  "logs": [
    // ... all log entries (not paginated)
  ]
}
When requesting logs, the API automatically deletes entries older than 7 days before returning results. This cleanup happens on every GET request.

​
Automatic Cleanup

Each time you request audit logs, the API automatically removes entries older than DAYS_TO_KEEP (default: 7 days): 
await prisma.auditLog.deleteMany({
  where: {
    createdAt: {
      lt: new Date(Date.now() - DAYS_TO_KEEP * 24 * 60 * 60 * 1000),
    },
  },
});

​
Filtering

The API supports case-insensitive partial matching on:
  • user: Filters by userName field
  • action: Filters by action field
Combine multiple filters to narrow results: 
// Find all "deleted" actions by "John"
const response = await fetch('/api/audit-log?user=john&action=deleted&all=true');
const { logs } = await response.json();

​
Pagination

By default, the API returns 5 logs per page. Use the page parameter to navigate: 
// Page 1
const page1 = await fetch('/api/audit-log?page=1');
const { logs: logs1, total } = await page1.json();

// Page 2
const page2 = await fetch('/api/audit-log?page=2');
const { logs: logs2 } = await page2.json();

// Calculate total pages
const totalPages = Math.ceil(total / 5);

​
Common Actions

Recommended action values for consistency:
  • created - Item was created
  • updated - Item was modified
  • deleted - Item was deleted
  • completed - Task was completed
  • invited - User was invited
  • accepted - Invitation was accepted
  • declined - Invitation was declined

​
Error Responses

​
500 Internal Server Error
Unexpected server error
Internal Server Error
The GET endpoint does not require authentication in the current implementation. For production use, consider adding authentication to protect sensitive activity data.

​
Source Code Reference

  • Create log: ~/workspace/source/src/app/api/audit-log/route.ts:28
  • Get logs: ~/workspace/source/src/app/api/audit-log/route.ts:55
  • User identity: ~/workspace/source/src/app/api/audit-log/route.ts:13

Build docs developers (and LLMs) love

Get started for freeTalk to us