> 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/platform-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/jdb1sa9YdhuzvIN7xCPG" 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><p></p><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><p></p><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><p></p><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><p></p><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><p></p><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><p></p><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><p></p><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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.wearepatchworks.com/product-documentation/general-settings/platform-audit-logs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.