> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt > Use this file to discover all available pages before exploring further. # List audit logs > Return a paginated list of audit logs filtered by query parameters such as userId, event type, date range, etc. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json get /api/audit-logs openapi: 3.1.0 info: title: Cotool API version: 1.0.0 description: >- # Cotool API Documentation The Cotool API allows you to interact with the Cotool platform programmatically, enabling you to build powerful integrations and automate your workflows. ## Getting an API Key Follow these steps to generate your API key: 1. **Log in** to the Cotool web interface 2. **Navigate** to `/settings/api-keys` 3. **Click** "Generate Key" 4. **Copy and store** your API key securely ⚠️ *It won't be shown again* ## API Key Authentication For programmatic access and integrations, use your API key with the Authorization header: ```http Authorization: Bearer your_api_key_here ``` ```bash curl -X GET "https://app.cotool.ai/api/endpoint" \ -H "Authorization: Bearer your_api_key_here" \ -H "Content-Type: application/json" ``` servers: - url: https://app.cotool.ai description: Production server security: - ApiKeyAuth: [] paths: /api/audit-logs: get: tags: - Audit Logs summary: List audit logs description: >- Return a paginated list of audit logs filtered by query parameters such as userId, event type, date range, etc. parameters: - in: query name: userId description: Filter audit logs by specific user ID schema: type: string minLength: 1 description: Filter audit logs by specific user ID - in: query name: event description: Filter audit logs by event type (e.g., user.login, agent.runStarted) schema: type: string description: >- Filter audit logs by event type (e.g., user.login, agent.runStarted) - in: query name: actor description: Filter audit logs by actor type (user, agent, chat) schema: type: string description: Filter audit logs by actor type (user, agent, chat) - in: query name: chatId description: Filter audit logs by specific chat ID schema: type: string minLength: 1 description: Filter audit logs by specific chat ID - in: query name: agentId description: Filter audit logs by specific agent ID schema: type: string minLength: 1 description: Filter audit logs by specific agent ID - in: query name: triggerId description: Filter audit logs by specific trigger ID schema: type: string minLength: 1 description: Filter audit logs by specific trigger ID - in: query name: toolGroup description: >- Filter audit logs by tool family (e.g. "slack" matches data.toolId = "slack" and any "slack_*" tool) schema: type: string description: >- Filter audit logs by tool family (e.g. "slack" matches data.toolId = "slack" and any "slack_*" tool) - in: query name: startDate description: Filter audit logs from this date onwards (ISO string format) schema: type: string description: Filter audit logs from this date onwards (ISO string format) - in: query name: endDate description: Filter audit logs up to this date (ISO string format) schema: type: string description: Filter audit logs up to this date (ISO string format) - in: query name: search description: >- Text search across event type, actor, user email, agent name, and data fields schema: type: string description: >- Text search across event type, actor, user email, agent name, and data fields - in: query name: limit description: 'Maximum number of audit logs to return (1-100, default: 50)' schema: type: integer minimum: 1 maximum: 100 default: 50 description: 'Maximum number of audit logs to return (1-100, default: 50)' - in: query name: offset description: 'Number of audit logs to skip for pagination (default: 0)' schema: type: integer minimum: 0 default: 0 description: 'Number of audit logs to skip for pagination (default: 0)' - in: query name: sortBy description: 'Field to sort audit logs by (default: timestamp)' schema: type: string enum: - timestamp - createdAt default: timestamp description: 'Field to sort audit logs by (default: timestamp)' - in: query name: sortDirection description: 'Sort direction for audit logs (default: desc)' schema: type: string enum: - asc - desc default: desc description: 'Sort direction for audit logs (default: desc)' responses: '200': description: Successful response content: application/json: schema: type: array items: type: object properties: id: type: string minLength: 1 description: Unique identifier for this audit log entry timestamp: type: string description: When the audited event occurred organizationId: type: string format: uuid description: Organization where the event took place event: type: string description: >- Type of event that was audited (e.g., user.login, agent.runStarted) actor: type: string description: Who or what performed the action (user, agent, chat) userId: type: - string - 'null' format: uuid description: >- ID of the user involved in the event (null if not applicable) ipAddress: type: - string - 'null' description: >- IP address where the event originated (null if not applicable) chatId: type: - string - 'null' format: uuid description: >- ID of the chat involved in the event (null if not applicable) agentId: type: - string - 'null' format: uuid description: >- ID of the agent involved in the event (null if not applicable) runId: type: - string - 'null' format: uuid description: >- ID of the agent run involved in the event (null if not applicable) triggerId: type: - string - 'null' format: uuid description: >- ID of the trigger involved in the event (null if not applicable) data: type: - object - 'null' additionalProperties: {} description: Additional event-specific data (null if no extra data) createdAt: type: string description: When this audit log entry was created in the database user: type: object properties: email: type: string description: >- Email address of the user associated with this audit log required: - email description: Hydrated user information (included when available) agent: type: object properties: name: type: string description: >- Display name of the agent associated with this audit log required: - name description: Hydrated agent information (included when available) trigger: type: object properties: name: type: string description: >- Display name of the trigger associated with this audit log type: type: string description: Type of trigger (e.g., jira, slack, linear, cron) required: - name - type description: Hydrated trigger information (included when available) required: - id - timestamp - organizationId - event - actor - userId - ipAddress - chatId - agentId - runId - triggerId - data - createdAt description: >- Complete audit log entry with optional hydrated relationship data description: Array of audit log entries matching the specified filters '400': description: Bad request — input validation failed or the request was malformed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized — missing or invalid API key / session content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — the authenticated user lacks the required permissions content: application/json: schema: $ref: '#/components/schemas/PermissionError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: |- curl -X GET "https://app.cotool.ai/api/audit-logs" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" components: schemas: ValidationError: type: object properties: error: type: string description: Error message describing what went wrong issues: type: array description: >- Detailed validation issues, present when request or response schema validation fails items: type: object additionalProperties: true required: - error Error: type: object properties: error: type: string description: Error message describing what went wrong required: - error PermissionError: type: object properties: error: type: string description: Error message describing what went wrong missingPerms: type: array description: Permissions the authenticated user is missing for this operation items: type: string required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key authentication for programmatic access. Include your API key in the Authorization header as: `Bearer your_api_key_here` ````