> For the complete documentation index, see [llms.txt](https://docs.clearfeed.ai/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clearfeed.ai/api/reference/api-reference/audit-logs.md).

# Audit Logs

Audit logs record actions performed on your ClearFeed account for compliance and security auditing.

{% hint style="warning" %}
These endpoints require an admin API token. Non-admin tokens receive a 403 Forbidden response.
{% endhint %}

## Audit Log Entry Object

Each audit log entry is a JSON object with the following properties.

<table data-full-width="true"><thead><tr><th width="200">Name</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td>created_at</td><td>string (ISO 8601)</td><td>Timestamp when the action occurred.</td></tr><tr><td>actor_name</td><td>string</td><td>Display name of the user who performed the action.</td></tr><tr><td>actor_email</td><td>string</td><td>Email of the user who performed the action.</td></tr><tr><td>operation</td><td>enum</td><td>One of: <code>access</code> (read operations) or <code>update</code> (write operations).</td></tr><tr><td>action</td><td>string</td><td>Description of the action (e.g., <code>"Updated customer"</code>, <code>"Created custom field"</code>).</td></tr><tr><td>resource_type</td><td>enum</td><td>Type of resource affected. One of: <code>Account</code>, <code>Request</code>, <code>Collection</code>, <code>SlackChannel</code>, <code>Customer</code>, <code>CustomField</code>, <code>Announcement</code>.</td></tr><tr><td>resource_ids</td><td>string array | null</td><td>External identifiers of the affected resource(s). Null for list and search operations.</td></tr><tr><td>details</td><td>object | null</td><td>Additional structured context. Shape varies by action type. Null for most entries.</td></tr><tr><td>source</td><td>enum</td><td>Channel through which the action was performed. One of: <code>API</code>, <code>Dashboard</code>, <code>Slack</code>.</td></tr><tr><td>ip_address</td><td>string | null</td><td>IP address of the requester. Null for Slack-originated or system actions.</td></tr></tbody></table>

## List Audit Logs

<mark style="color:blue;">`GET`</mark> `https://api.clearfeed.app/v1/rest/audit-logs`

Retrieve a paginated list of audit log entries for the account.

#### Query Parameters

All parameters are optional.

<table data-full-width="true"><thead><tr><th width="200">Name</th><th width="104">Type</th><th>Description</th></tr></thead><tbody><tr><td>actor_email</td><td>string</td><td>Filter by actor email address (max 255 chars, case-insensitive).</td></tr><tr><td>operation</td><td>enum</td><td>Filter by operation type. One of: <code>access</code> or <code>update</code>.</td></tr><tr><td>resource_type</td><td>enum</td><td>Filter by resource type. One of: <code>Account</code>, <code>Request</code>, <code>Collection</code>, <code>SlackChannel</code>, <code>Customer</code>, <code>CustomField</code>, <code>Announcement</code>.</td></tr><tr><td>source</td><td>enum</td><td>Filter by source. One of: <code>API</code>, <code>Dashboard</code>, <code>Slack</code>.</td></tr><tr><td>before</td><td>string</td><td>Fetch records created before this timestamp (ISO 8601). Cannot be in the future.</td></tr><tr><td>after</td><td>string</td><td>Fetch records created after this timestamp (ISO 8601). Cannot be in the future. Must be earlier than <code>before</code> when both are provided.</td></tr><tr><td>sort_order</td><td>enum</td><td>Sort order for results. One of: <code>asc</code> or <code>desc</code>. Defaults to <code>desc</code> (newest first).</td></tr><tr><td>limit</td><td>integer</td><td>Number of results to return (1–100). Defaults to 50.</td></tr><tr><td>next_cursor</td><td>string</td><td>Base64-encoded cursor for pagination. Obtained from <code>metadata.next_cursor</code> in a previous response.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```json
{
  "data": [
    {
      "created_at": "2026-04-15T10:30:00.000Z",
      "actor_name": "Alice Smith",
      "actor_email": "alice@example.com",
      "operation": "update",
      "action": "Updated customer",
      "resource_type": "Customer",
      "resource_ids": ["42"],
      "details": null,
      "source": "API",
      "ip_address": "203.0.113.5"
    },
    {
      "created_at": "2026-04-15T10:28:00.000Z",
      "actor_name": "Bob Jones",
      "actor_email": "bob@example.com",
      "operation": "access",
      "action": "Listed requests",
      "resource_type": "Request",
      "resource_ids": null,
      "details": null,
      "source": "Dashboard",
      "ip_address": "203.0.113.10"
    }
  ],
  "metadata": {
    "next_cursor": "MTIz",
    "count": 2
  }
}
```

`metadata.next_cursor` is `null` when there are no more pages. `metadata.count` is the number of entries in the current `data` array.
{% endtab %}

{% tab title="403: Forbidden Permission denied" %}

{% endtab %}
{% endtabs %}

## Export Audit Logs

<mark style="color:blue;">`GET`</mark> `https://api.clearfeed.app/v1/rest/audit-logs/export`

Download audit log entries as a CSV file. Accepts the same filter parameters as the List endpoint.

#### Query Parameters

All parameters are optional.

<table data-full-width="true"><thead><tr><th width="200">Name</th><th width="104">Type</th><th>Description</th></tr></thead><tbody><tr><td>actor_email</td><td>string</td><td>Filter by actor email address (max 255 chars, case-insensitive).</td></tr><tr><td>operation</td><td>enum</td><td>Filter by operation type. One of: <code>access</code> or <code>update</code>.</td></tr><tr><td>resource_type</td><td>enum</td><td>Filter by resource type. One of: <code>Account</code>, <code>Request</code>, <code>Collection</code>, <code>SlackChannel</code>, <code>Customer</code>, <code>CustomField</code>, <code>Announcement</code>.</td></tr><tr><td>source</td><td>enum</td><td>Filter by source. One of: <code>API</code>, <code>Dashboard</code>, <code>Slack</code>.</td></tr><tr><td>before</td><td>string</td><td>Fetch records created before this timestamp (ISO 8601). Cannot be in the future.</td></tr><tr><td>after</td><td>string</td><td>Fetch records created after this timestamp (ISO 8601). Cannot be in the future. Must be earlier than <code>before</code> when both are provided.</td></tr><tr><td>limit</td><td>integer</td><td>Maximum number of rows in the CSV (1–10000). Defaults to 1000. To export a large date range completely, partition it into time-bounded batches using <code>before</code> and <code>after</code>.</td></tr></tbody></table>

{% tabs %}
{% tab title="200: Success" %}
Returns a CSV file.

**Response Headers:**

* `Content-Type: text/csv`
* `Content-Disposition: attachment; filename="audit-logs-{accountId}-{YYYY-MM-DD}.csv"`

**CSV Columns (in order):** `timestamp`, `actor_name`, `actor_email`, `operation`, `action`, `resource_type`, `resource_ids`, `details`, `source`, `ip_address`

**Column notes:**

* `timestamp` — ISO 8601 UTC (e.g., `2026-04-15T10:30:00.000Z`)
* `resource_ids` — comma-and-space-separated list; empty string if none
* details — JSON-serialized; empty string if null
* `ip_address` — empty string if not available
  {% endtab %}

{% tab title="403: Forbidden Permission denied" %}

{% endtab %}
{% endtabs %}