COcotool
Audit Logs

List audit logs

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.

get/api/audit-logs

Request

  • Base URL
    https://app.cotool.ai
  • Auth
    HTTP bearer

Query parameters

userIdstring

Filter audit logs by specific user ID

eventstring

Filter audit logs by event type (e.g., user.login, agent.runStarted)

actorstring

Filter audit logs by actor type (user, agent, chat)

chatIdstring

Filter audit logs by specific chat ID

agentIdstring

Filter audit logs by specific agent ID

triggerIdstring

Filter audit logs by specific trigger ID

toolGroupstring

Filter audit logs by tool family (e.g. "slack" matches data.toolId = "slack" and any "slack_*" tool)

mcpConnectionIdstring uuid

Filter audit logs to one MCP app connection (via.connectionId or data.mcpApp.connectionId)

startDatestring

Filter audit logs from this date onwards (ISO string format)

endDatestring

Filter audit logs up to this date (ISO string format)

searchstring

Text search across event type, actor, user email, agent name, and data fields

limitinteger

Maximum number of audit logs to return (1-100, default: 50)

offsetinteger

Number of audit logs to skip for pagination (default: 0, max: 10000). For continuous export or deep pagination, use cursor pagination instead.

cursorstring

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

Successful response

idstring required

Unique identifier for this audit log entry

timestampstring required

When the audited event occurred

organizationIdstring uuid required

Organization where the event took place

eventstring required

Type of event that was audited (e.g., user.login, agent.runStarted)

actorstring required

Who or what performed the action (user, agent, chat)

userIdstring uuid nullable required

ID of the user involved in the event (null if not applicable)

ipAddressstring nullable required

IP address where the event originated (null if not applicable)

chatIdstring uuid nullable required

ID of the chat involved in the event (null if not applicable)

agentIdstring uuid nullable required

ID of the agent involved in the event (null if not applicable)

runIdstring uuid nullable required

ID of the agent run involved in the event (null if not applicable)

triggerIdstring uuid nullable required

ID of the trigger involved in the event (null if not applicable)

dataobject nullable required

Additional event-specific data (null if no extra data)

createdAtstring required

When this audit log entry was created in the database

Changes

No recorded changes to this operation across all 2 revisions of this API.