> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/reference/audit-log/overview/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Audit Log API

The Audit log API gives you programmatic oversight of every change to your Ada instance. It provides a consistent, programmatic way to retrieve who changed what, from where, and when, and pull that record into a SIEM or other security tooling.

Download full OpenAPI spec

You can access the Audit log in two ways:

* **Pull:** Call `GET /api/v2/analytics/audit-log/events/` to retrieve events for a time window and page through the results. This is the durable record, so use it as your source of truth.
* **Push:** Subscribe to the `v1.audit_log.emitted` webhook to receive each change in real time. Delivery is best-effort, so use the pull endpoint to reconcile any missed events.

Every event returned is scoped to your own instance. Requests authenticate with a Platform API key; see [Authentication](/reference/introduction/authentication).

## Coverage and limitations

The Audit log records changes to the following surfaces:

* **AI Agent configuration:** playbooks, processes, actions, knowledge (articles and sources), coaching, handoffs, greeting, proactives, variables, glossary terms, topics, intents, test cases, and simulation runs.
* **Security and access:** API keys, team membership and roles, SSO, and session limits.

The following are not yet captured and will be added in future releases:

* **Channels:** Web Chat, Email, Voice, and Social channel settings.
* **Integrations:** apps and action integrations, platform integrations, and MCP connections.
* **Security and privacy settings:** for example, redactions.
* **Other Agent configuration:** persona, languages, CSAT, schedules, article syncs, and persistence.
* **Webhook subscriptions:** changes you make to your own webhook endpoints.
* **Public API operations:** data exports and data compliance erasures.

## Pagination

Results come back newest first, paginated with a cursor. Read `meta.next_page_url` and replay it verbatim to fetch the next page, until the value is `null`, which marks the last page.

> **Note**
>
> Don't modify the URL between pages. The time window and cursor are encoded in it, and changing them returns a `400`.

## Filtering and time windows

The only filter is the time window; there are no server-side field filters. Retrieve the full window and filter within your SIEM or other security tooling.

A single request covers at most 30 days (`end_date - start_date`).

* **Backfill history** by issuing successive requests over adjacent 30-day windows, walking backward until you reach the earliest data you need.
* **Pull incrementally** by setting `start_date` to just after the newest `timestamp` you have already stored, then following `next_page_url` until it is `null`.

## Event schema

Each Audit log record captures the following:

* **Actor:** who made the change, via `actor_email`, `actor_name`, `actor_user_id`, plus `api_key_name` when the change came from an API key. Actor fields are empty for system and service-token changes.
* **Entity:** what changed, via `entity_type`, `entity_id`, `entity_name`.
* **Activity:** the kind of change: `created`, `updated`, `deleted`, `executed`, `invited`, `activated`, or `deactivated`.
* **Interface:** where the change came through: `dashboard`, `api`, `mcp`, `cli`, `import`, `export`, or `system`.
* **Context:** the `context_ip` and `context_user_agent` of the change request.

Each record also has a unique `id` and a `timestamp` (ISO 8601, UTC) marking when the change occurred. See the [endpoint reference](/reference/audit-log/list-audit-log-events) for the full field list and examples.

## Rate limits

The pull endpoint enforces these per-instance limits:

* Requests per day: 40,000
* Requests per minute: 120
* Requests per second: 10

A `429` response means a limit was exceeded; back off and retry. For ongoing ingestion, poll on a steady cadence (for example, every few minutes) rather than in a tight loop.

## Webhook support

Subscribe to the `v1.audit_log.emitted` webhook in the Ada dashboard to receive each configuration change as it happens. On the webhook page in the dashboard, use channel filters to scope which events your endpoint receives by `entity_type` (the `article` entity type is delivered on the `knowledge` channel). For setup steps, see the [webhook documentation](/reference/webhooks/overview).

> **Info**
>
> **If you use IP allowlisting:** Ada delivers webhooks through Svix. If your firewall only accepts traffic from approved source IPs, review [this section](/reference/webhooks/overview#ip-allowlist) for full details.

> Overview