---
title: "List audit logs"
method: GET
path: "/api/audit-logs"
tags: ["Audit Logs"]
---

# List audit logs

`GET /api/audit-logs`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/audit-logs`
- Auth: HTTP bearer

Return a paginated list of audit logs filtered by query parameters such as userId, event type, date range, etc. Supports two pagination modes: limit/offset (default), and keyset cursors for continuous export — when a page is full, the X-Next-Cursor response header carries an opaque cursor for the next page; pass it back as the cursor query parameter. An absent header (or a short page) means there is no more data. Cursor pages stay equally fast at any depth, unlike large offsets.

## Query parameters

- `userId` string: Filter audit logs by specific user ID
- `event` string: Filter audit logs by event type (e.g., user.login, agent.runStarted)
- `actor` string: Filter audit logs by actor type (user, agent, chat)
- `chatId` string: Filter audit logs by specific chat ID
- `agentId` string: Filter audit logs by specific agent ID
- `triggerId` string: Filter audit logs by specific trigger ID
- `toolGroup` string: Filter audit logs by tool family (e.g. "slack" matches data.toolId = "slack" and any "slack_*" tool)
- `mcpConnectionId` string, uuid: Filter audit logs to one MCP app connection (via.connectionId or data.mcpApp.connectionId)
- `startDate` string: Filter audit logs from this date onwards (ISO string format)
- `endDate` string: Filter audit logs up to this date (ISO string format)
- `search` string: Text search across event type, actor, user email, agent name, and data fields
- `limit` integer: Maximum number of audit logs to return (1-100, default: 50)
- `offset` integer: Number of audit logs to skip for pagination (default: 0, max: 10000). For continuous export or deep pagination, use cursor pagination instead.
- `cursor` string: Opaque keyset-pagination cursor from the X-Next-Cursor response header of the previous page. Preferred over offset for continuous export: pages stay equally fast at any depth and an empty page means there is no more data. Mutually exclusive with offset; only supported with sortBy=timestamp.
- `sortBy` 'timestamp' | 'createdAt': Field to sort audit logs by (default: timestamp)
- `sortDirection` 'asc' | 'desc': Sort direction for audit logs (default: desc)

## Response `200`

Successful response

- object[]: Array of audit log entries matching the specified filters
  - `id` string, required: Unique identifier for this audit log entry
  - `timestamp` string, required: When the audited event occurred
  - `organizationId` string, uuid, required: Organization where the event took place
  - `event` string, required: Type of event that was audited (e.g., user.login, agent.runStarted)
  - `actor` string, required: Who or what performed the action (user, agent, chat)
  - `userId` string, uuid, nullable, required: ID of the user involved in the event (null if not applicable)
  - `ipAddress` string, nullable, required: IP address where the event originated (null if not applicable)
  - `chatId` string, uuid, nullable, required: ID of the chat involved in the event (null if not applicable)
  - `agentId` string, uuid, nullable, required: ID of the agent involved in the event (null if not applicable)
  - `runId` string, uuid, nullable, required: ID of the agent run involved in the event (null if not applicable)
  - `triggerId` string, uuid, nullable, required: ID of the trigger involved in the event (null if not applicable)
  - `data` object, nullable, required: Additional event-specific data (null if no extra data)
  - `via` object, nullable: The app the user acted through, such as an app connected to the Cotool MCP server (null for actions taken directly in Cotool or with an API key)
    - `appName` string, required
    - `connectionId` string, required
    - `clientId` string, required
    - `type` 'mcp', required
    - `publisher` string, nullable, required
  - `createdAt` string, required: When this audit log entry was created in the database
  - `user` object: Hydrated user information (included when available)
    - `email` string, required: Email address of the user associated with this audit log
  - `agent` object: Hydrated agent information (included when available)
    - `name` string, required: Display name of the agent associated with this audit log
  - `trigger` object: Hydrated trigger information (included when available)
    - `name` string, required: Display name of the trigger associated with this audit log
    - `type` string, required: Type of trigger (e.g., jira, slack, linear, cron)

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `500`: Internal server error

---

[API](https://skmtc.dev/cotool/apis/cotool-api.md) - [All operations](https://skmtc.dev/cotool/apis/cotool-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cotool/apis/cotool-api/revisions/f5abe0add203?raw)