> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/general-settings/audit-logs.md).

# Platform ( Audit ) logs

## Introduction

Platform Logs give you a centralised, chronological view of all activity across your Patchworks account - from user logins and settings changes to role management and error events. Use them to monitor what's happening, investigate incidents, and maintain a full audit trail.

{% hint style="info" %}
**Requires admin access.** Only users with an admin role can view Platform Logs.
{% endhint %}

## Where to find Platform Logs <a href="#h-where" id="h-where"></a>

Platform Logs live inside the **Settings** section of the main navigation. You'll see it listed as the fourth option on the Settings landing page.

1. Click the **Settings** icon in the left-hand navigation bar.
2. On the Settings landing page, select **Platform Logs -** labelle&#x64;*"View platform-wide activity logs"*.
3. The logs list loads automatically, defaulting to the **All** tab, ordered newest-first.

<figure><img src="/files/ZjFo5gQ8slaBhVGNyiYv" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/wlbQfSab6UlroehiOhMM" alt="Settings page showing Platform Logs option"><figcaption><p>Settings landing page - Platform Logs is the fourth item</p></figcaption></figure>

\
Viewing logs across multiple companies
--------------------------------------

If your account manages multiple child companies, you can use the **Viewing company** dropdown to scope logs to any combination of companies - or select **All companies** to see everything in one feed.

1. Open **Platform Logs** from Settings.
2. Click the **Viewing company** dropdown - it defaults to your current active company.
3. Select **All companies** to see every company's logs together, or use the search box within the dropdown to find and tick individual child companies.
4. Click **Apply** to reload the list with your selection

<figure><img src="/files/jlOQ83Ror6i9GrMn4FoU" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Each log entry displays a **company chip** (e.g. `Test Dev Account`) so you can always tell which company an event belongs to when viewing across multiple companies.
{% endhint %}

## Filtering Logs

Use the filter bar at the top of the page to narrow down the log entries displayed. Filters are applied together when you click **Apply**.

| Filter          | Description                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| Viewing company | Select which company's logs to display. Switch between all managed companies from this dropdown.         |
| Search logs     | Free-text search across log event names and actor names (e.g. search `Conor` or `Role Created`).         |
| From date       | Filter to logs recorded on or after this date. Accepts `dd/mm/yyyy` format.                              |
| To date         | Filter to logs recorded on or before this date. Use together with *From date* to define a precise range. |
| Order           | Sort results by **Newest first** or **Oldest first**.                                                    |

{% hint style="success" %}
Click **Clear** to reset all filters back to their defaults without leaving the page.
{% endhint %}

#### Log tabs

| Tab     | What it contains                                                                       |
| ------- | -------------------------------------------------------------------------------------- |
| All     | Every log entry across all categories - the default view.                              |
| Audit   | Read-only activity: logins, logouts, password resets, session events.                  |
| Changes | Mutative events: entity creations, updates, and deletions.                             |
| Errors  | Failed operations and system-level error events. A count of 0 is the healthy baseline. |

## Colour reference <a href="#h-colours" id="h-colours"></a>

Each log entry has a coloured dot that lets you instantly identify its category and sub-type without reading the event name. Here is the full reference:

<table><thead><tr><th>Dot</th><th>Colour / shade</th><th>Category</th><th>Event types</th></tr></thead><tbody><tr><td><pre><code>🟢
</code></pre></td><td>Green</td><td>Creations &#x26; reactivations</td><td><code>created</code>, <code>user_reactivated</code></td></tr><tr><td><pre><code>🟠
</code></pre></td><td>Orange — darker</td><td>Assignments</td><td><code>tier_assigned</code>, <code>subscription_assigned</code></td></tr><tr><td></td><td>Orange — lighter</td><td>Updates</td><td><code>updated</code>, <code>user_updated</code>, <code>mapping_created</code></td></tr><tr><td><pre><code>🔴 
</code></pre></td><td>Red-700 (darkest)</td><td>Force deletions</td><td><code>company_force_deleted</code></td></tr><tr><td></td><td>Red-500</td><td>Deletions</td><td><code>deleted</code>, <code>user_deleted</code>, <code>company_deleted</code></td></tr><tr><td></td><td>Red-400 (lightest)</td><td>Soft removals</td><td><code>deduped_data_bulk_deleted</code>, <code>tier_removed</code>, <code>subscription_removed</code></td></tr><tr><td></td><td>Red-600</td><td>Errors (level = error)</td><td>Any entry where the log <code>level</code> field is <code>error</code>. These appear in the <strong>Errors</strong> tab.</td></tr><tr><td><pre><code>🟣
</code></pre></td><td>Purple — bold</td><td>Auth &#x26; account management</td><td><code>login</code>, <code>two_factor_enabled</code>, <code>two_factor_confirmed</code>, <code>password_updated</code>, <code>password_reset</code>, <code>oidc_assignment_created</code></td></tr><tr><td></td><td>Purple — mid</td><td>Auth &#x26; account management</td><td><code>logout</code>, <code>two_factor_disabled</code>, <code>password_reset_requested</code>, <code>oidc_assignment_deleted</code>, <code>user_invite_sent</code></td></tr><tr><td></td><td>Purple — faint</td><td>Auth failures</td><td><code>password_update_failed</code>, <code>password_reset_failed</code></td></tr><tr><td><pre><code>🔵
</code></pre></td><td>Blue</td><td>Data operations</td><td><code>marketplace_app_installed</code>, <code>deduped_data_imported</code></td></tr><tr><td></td><td>Blue — lighter</td><td>Data exports</td><td><code>deduped_data_exported</code>, <code>mapping_exported</code></td></tr><tr><td><pre><code>🟡
</code></pre></td><td>Yellow</td><td>Flow canvas</td><td><code>flow_step_connected</code>, <code>flow_step_disconnected</code></td></tr><tr><td><pre><code> ⚫
</code></pre></td><td>Grey</td><td>Unrecognised</td><td>Any event type not matched by the above - may be a newer event type not yet assigned a colour.</td></tr></tbody></table>

{% hint style="success" %}
Use the colour dots as a quick visual triage tool when reviewing the **All** tab - a dense cluster of red or faint-purple dots is a signal worth investigating even before reading the event names.
{% endhint %}

### Log retention period <a href="#h-retention" id="h-retention"></a>

By default, Platform Logs are retained for **90 days**. Submit a request to increase this up to a maximum of **180 days** from the **Company Admin** page. Logs older than the configured retention period are automatically purged.

1. Navigate to **Company Admin** (accessible from the main navigation or your account menu).
2. Scroll to the **Log settings** section at the bottom of the page.
3. Here, a Patchworks admin can adjust the **Log retention period (days)** field - the default is`90`, and the maximum is `180`.

<figure><img src="/files/JqjGFYLacjfqr5DLewnG" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Retention is per-company.** If you manage multiple child companies, each company has its own independent retention setting. Navigate to each company's Company Admin page to adjust them individually.
{% endhint %}

{% hint style="warning" icon="triangle-exclamation" %}
Reducing the retention period will **immediately** schedule older logs for deletion. Logs outside the new window cannot be recovered once purged. Export any logs you need before reducing this value
{% endhint %}

### Setting up Alerts <a href="#h-alerts" id="h-alerts"></a>

Alerts let you get notified automatically when specific log events occur - without having to manually check the Platform Logs page. For example, you can receive an alert whenever a login fails, or when a critical API error is recorded.

Alerts are managed separately at **Settings → Alerts**.

1. Go to **Settings** in the left-hand navigation.
2. Select **Alerts** from the Settings menu.
3. Click the **+ Create Alert** button in the top-right corner.
4. Enter a **Name** for your alert (e.g. *Error Alert*, *Login Failed Monitor*).
5. Choose an **Alert Type**: currently **Error** is supported, with audit and change types coming soon.
6. Select the specific **Event** to trigger on - for Error type, options include *Api Server Error*, *Failed Save*, and *Login Failed*.
7. Click **Save**. The alert will appear in your alerts list and trigger whenever that event is logged.

<figure><img src="/files/KrRffU3r0wxrn2eT6wjq" alt=""><figcaption></figcaption></figure>

#### Available alert events

| Alert Type | Event              | When it fires                                                                        |
| ---------- | ------------------ | ------------------------------------------------------------------------------------ |
| Error      | `Api Server Error` | An API call to an external service returns an unexpected server-side error.          |
|            | `Failed Save`      | A data-save operation fails - e.g. a connector or mapping could not persist changes. |
|            | `Login Failed`     | A user authentication attempt fails (bad credentials, locked account, etc.).         |

{% hint style="success" %}
Combine alerts with **Notification Groups** (Settings → Notification Groups) to route alert notifications to specific team members or channels like Slack or email.
{% endhint %}