> 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, and calls ClearFeed makes to connected systems on your behalf, 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>integration</td><td>enum</td><td>System the action was performed against. One of: <code>clearfeed</code> or <code>hubspot</code>.</td></tr><tr><td>actor_name</td><td>string</td><td>Display name of the user who performed the action. <code>ClearFeed System</code> for system-performed actions.</td></tr><tr><td>actor_email</td><td>string</td><td>Email of the user who performed the action. <code>Unknown</code> for system-performed actions.</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>"Sent message to HubSpot conversation"</code>).</td></tr><tr><td>resource_type</td><td>enum</td><td>Type of resource affected. See <a href="#resource-types">Resource Types</a>.</td></tr><tr><td>resource_ids</td><td>string array | null</td><td>Identifiers of the affected resource(s). Null when no identifiers were captured.</td></tr><tr><td>details</td><td>object | null</td><td>Additional structured context. See <a href="#details">Details</a>. Null for most <code>clearfeed</code> 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>, <code>Microsoft Teams</code>, <code>Discord</code>, <code>Telegram</code>, <code>ClearFeed Support</code>, <code>System</code>.</td></tr><tr><td>ip_address</td><td>string | null</td><td>IP address of the requester.</td></tr></tbody></table>

## Details

Keys present on entries for calls to connected systems (`integration: "hubspot"`). Optional keys are omitted when they do not apply.

<table data-full-width="true"><thead><tr><th width="200">Key</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td>method</td><td>string</td><td>HTTP method of the call. One of: <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>.</td></tr><tr><td>outcome</td><td>enum</td><td>One of: <code>success</code> or <code>failure</code>.</td></tr><tr><td>statusCode</td><td>integer</td><td>HTTP status code returned. Omitted when the call failed without an HTTP response.</td></tr><tr><td>retries</td><td>integer</td><td>Number of retry attempts. Omitted when the call was not retried.</td></tr><tr><td>requestIds</td><td>integer array</td><td>ClearFeed request number(s) the call is attributed to. Omitted when no request applies.</td></tr><tr><td>jobName</td><td>enum</td><td>Job that made the call, when <code>source</code> is <code>System</code>. One of: <code>CRM Sync</code>, <code>Automation</code>, <code>AI-Agent</code>.</td></tr><tr><td>automationId</td><td>integer</td><td>Automation number, when <code>jobName</code> is <code>Automation</code>.</td></tr><tr><td>aiAgentId</td><td>integer</td><td>AI agent number, when <code>jobName</code> is <code>AI-Agent</code>.</td></tr></tbody></table>

## Resource Types

**`clearfeed`:** `Account`, `Request`, `Collection`, `SlackChannel`, `TelegramChannel`, `DiscordChannel`, `Customer`, `CustomField`, `CustomStatus`, `Rotation`, `EmailDomain`, `EmailBlocklist`, `Agent`, `Announcement`, `Automation`, `QuickReply`

**`hubspot`:** `HubSpotAccount`, `HubSpotAssociation`, `HubSpotCompany`, `HubSpotContact`, `HubSpotConversation`, `HubSpotDeal`, `HubSpotEmail`, `HubSpotFile`, `HubSpotNote`, `HubSpotPipeline`, `HubSpotProperty`, `HubSpotTask`, `HubSpotTicket`, `HubSpotUser`

## 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>integration</td><td>enum</td><td>Filter by system. One of: <code>clearfeed</code> or <code>hubspot</code>.</td></tr><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. Any value listed in <a href="#resource-types">Resource Types</a>.</td></tr><tr><td>source</td><td>enum</td><td>Filter by source. One of: <code>API</code>, <code>Dashboard</code>, <code>Slack</code>, <code>Microsoft Teams</code>, <code>Discord</code>, <code>Telegram</code>, <code>ClearFeed Support</code>, <code>System</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",
      "integration": "clearfeed",
      "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:29:00.000Z",
      "integration": "hubspot",
      "actor_name": "Alice Smith",
      "actor_email": "alice@example.com",
      "operation": "update",
      "action": "Sent message to HubSpot conversation",
      "resource_type": "HubSpotConversation",
      "resource_ids": ["7391104456", "47806069113"],
      "details": {
        "method": "POST",
        "outcome": "success",
        "statusCode": 201,
        "requestIds": [1026]
      },
      "source": "Slack",
      "ip_address": null
    }
  ],
  "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>integration</td><td>enum</td><td>Filter by system. One of: <code>clearfeed</code> or <code>hubspot</code>.</td></tr><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. Any value listed in <a href="#resource-types">Resource Types</a>.</td></tr><tr><td>source</td><td>enum</td><td>Filter by source. One of: <code>API</code>, <code>Dashboard</code>, <code>Slack</code>, <code>Microsoft Teams</code>, <code>Discord</code>, <code>Telegram</code>, <code>ClearFeed Support</code>, <code>System</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`, `integration`

**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 %}