> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Export the audit log

> Download your organization's audit log as CSV from the console, or read it page by page through the API with the read:audit scope.

The [audit log](/docs/reference/audit-log-events) records every
security-relevant action in your organization. It is append-only: entries
cannot be edited or deleted, and they leave the log only through
retention or when the organization is deleted.

On the Business plan and above you can export it, from the console as CSV
or through the API.

## Download CSV from the console

Open **Settings** > **Audit log**. The filter strip above the table sets
which entries the file holds:

* **From**: entries at or after this date (UTC), included.
* **Before**: entries before this date (UTC), not included.
* **Action**: an exact action (`page.created`) or a prefix ending in `.`
  (`page.`).

Select **Apply**. The table and the count next to the button show the
same entries the file will hold, for example "84 entries match". Then
select **Export CSV**. The file follows the same rules as the API's
`since`, `until` and `action` parameters, and an invalid filter is
refused instead of exporting the whole log. The table's other filters
(target, actor, IP) do not apply to the file.

Entries come newest first. A file holds at most **100,000 rows**. When
more entries match, the button reads **Export newest 100,000 as CSV**, the
file holds the newest 100,000, and its name ends in `-first-100000.csv`.
To export the rest, split the export into smaller date ranges with
**From** and **Before**, or read the full log through the
[API](#read-it-through-the-api).

Each download is itself recorded in the audit log as
`audit_log.exported`.

The CSV has these columns: `id`, `created_at`, `actor_type`,
`actor_user_id`, `actor_email`, `action`, `target_type`, `target_id`,
`ip`, `user_agent`, `metadata` (JSON). Cells that start with `=`, `+`,
`-` or `@` are prefixed with `'`, so a spreadsheet never runs them as a
formula.

## Read it through the API

Create an API key with the `read:audit` scope under **Settings** >
**API keys**, then call
[`GET /audit-log`](/api/audit/get-audit-log). From an MCP client, the tool
is `listAuditLog`.

```bash theme={null}
curl "https://use.observer/api/v1/audit-log?since=2026-10-01&action=page.&limit=100" \
  -H "Authorization: Bearer obs_pub_..."
```

| Parameter | Meaning |
| - | - |
| `limit` | Page size, 1 to 500. Default 100. |
| `cursor` | The `next_cursor` from the previous page. |
| `since` | Only entries at or after this ISO 8601 date or date and time. |
| `until` | Only entries before this ISO 8601 date or date and time. |
| `action` | An exact action (`page.created`) or a prefix ending in `.` (`page.`). |

Entries come newest first. Each response has `items` and `next_cursor`.
Keep requesting with `cursor` set to `next_cursor` until it is `null`:

```json theme={null}
{
  "items": [
    {
      "id": "48211",
      "created_at": "2026-10-14T09:12:03.512Z",
      "actor_type": "user",
      "actor_user_id": "user_...",
      "actor_email": "ana@example.com",
      "action": "page.access_changed",
      "target_type": "page",
      "target_id": "...",
      "metadata": { "mode": "sso" },
      "ip": "203.0.113.7",
      "user_agent": "Mozilla/5.0 ..."
    }
  ],
  "next_cursor": "..."
}
```

| Status | `title` | Meaning |
| - | - | - |
| `400` | `invalid_since`, `invalid_until` | Not an ISO 8601 date. |
| `400` | `invalid_action` | Not an action or a prefix ending in `.`. |
| `403` | `forbidden` | The key lacks `read:audit`. |
| `403` | `feature_locked` | Audit log export is on the Business and Enterprise plans. |
| `403` | `plan_does_not_permit_api` | The plan does not include the public API. |

## Retention

| Plan | Entries kept |
| - | - |
| Free, Starter, Pro | 90 days |
| Business, Enterprise | 1 year |
| Enterprise, by arrangement | Up to 7 years |

<Note>
  Longer retention on Business and Enterprise is rolling out. Until it is
  enabled for your organization, entries are kept for 90 days on every
  plan.
</Note>

When a plan change shortens retention, older entries are kept for another
30 days before they are removed. Export what you need to keep before
then.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.