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

# Audit Logs overview

> Understand what the Audit Logs API records, who can call it, and how action events differ from state-change events.

The Audit Logs API returns an immutable record of security-relevant actions
taken in your Circle entity, such as user sign-ins, approval requests, and
policy changes. Use it to review who did what, when, and from where.

## Availability

The Audit Logs API is available across all Circle products. Call it with the API
key from whichever Circle product you're integrating with.

## Retrieve audit log events

You can retrieve audit log events with two endpoints:

* [List audit logs](/api-reference/audit-logs/list-audit-logs) returns a
  paginated, newest-first list, filterable by time range, event type, actor, and
  outcome.
* [Get an audit log by ID](/api-reference/audit-logs/get-audit-log-by-id)
  returns a single audit log event by its `id`.

## Actor types

Every audit log event identifies an actor with `actorId` and `actorType`. The
actor type tells you what kind of identifier `actorId` is.

| Actor type | What it represents                                                                                                                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `USER`     | A human who performed the action through the [Circle Console](https://console.circle.com/), [Mint Console](https://app.circle.com/), or [CPN Console](https://cpn.circle.com/). `actorId` is the user's identifier. |
| `API_KEY`  | A Circle API key that performed the action programmatically. `actorId` is the API key's identifier.                                                                                                                 |
| `SYSTEM`   | Circle-internal automation that performed the action on your entity's behalf, such as expiring an approval request on its scheduled deadline.                                                                       |

## Action events and state-change events

Every audit log event is either an action event or a state-change event. The
`type` field tells you which, and determines which fields carry the event's
details.

* **Action events** record that something happened, with no prior or new
  resource state to compare.
* **State-change events** record a change to a resource in your entity, such as
  a policy update.

Both action and state-change events share a common set of fields that identify
who did what and when, such as `id`, `type`, `occurredAt`, or `actorId`. For
action events, additional fields specific to that event appear on `payload`.
State-change events populate `oldValues` (prior state) and `newValues` (new
state); `payload` might also carry additional context.

### Example action event

A `user.signed_in` event is an action event. It carries the client's user agent
on `payload`:

```json theme={null}
{
  "id": "abcdef01-2345-4678-9abc-def012345678",
  "type": "user.signed_in",
  "occurredAt": "2026-07-14T15:58:27.093995Z",
  "actorId": "example-user-id",
  "actorType": "USER",
  "clientIp": "203.0.113.42/32",
  "outcomeResult": "SUCCESS",
  "entityId": "deadbeef-1234-4567-89ab-cdef01234567",
  "requestId": "example-request-id-001",
  "payload": {
    "user_agent": "Mozilla/5.0 ..."
  }
}
```

### Example state-change event

A `policy.applied` event is a state-change event. It carries `oldValues` and
`newValues` alongside `payload`:

```json theme={null}
{
  "id": "01234567-89ab-4cde-8f01-234567890abc",
  "type": "policy.applied",
  "occurredAt": "2026-07-14T16:02:11.842Z",
  "actorId": "example-user-id",
  "actorType": "USER",
  "outcomeResult": "SUCCESS",
  "entityId": "deadbeef-1234-4567-89ab-cdef01234567",
  "requestId": "example-request-id-002",
  "oldValues": {
    "status": "inactive"
  },
  "newValues": {
    "status": "active"
  },
  "payload": {
    "action": "policy_change",
    "operation": "ACTIVATE",
    "scope": "RESOURCE"
  }
}
```

## Audit log event types

The following event types are recorded in the audit log. The list grows over
time as new products and controls add events. Your integration should tolerate
unknown `type` values and unknown keys inside `payload`.

### Sign-in events

Action events recorded when a user signs in to the
[Circle Console](https://console.circle.com/),
[Mint Console](https://app.circle.com/), or
[CPN Console](https://cpn.circle.com/). Actor is `USER` (see the
[example action event](#example-action-event)).

| Event type       | Recorded when                         |
| ---------------- | ------------------------------------- |
| `user.signed_in` | A user signed in to a Circle console. |

Each event's `payload` might carry the following fields:

| Field        | Type   | Required | Description                                            |
| ------------ | ------ | -------- | ------------------------------------------------------ |
| `email`      | string | No       | Email address of the user who signed in, if available. |
| `user_agent` | string | No       | `User-Agent` header of the authenticating client.      |

### Policy Engine events

Circle's Policy Engine records an immutable event each time an approval request
is resolved or a policy changes state. See
[Policy configuration, permissions, and approvals setup](https://help.circle.com/s/article/Policy-configuration-permissions-and-approvals-setup)
to set up policies and approval rules.

#### Approval request events

Action events recorded when an approval request is resolved. Actor is `USER`
(see the [example action event](#example-action-event)).

| Event type           | Recorded when                                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `proposal.approved`  | The request received the required approvals; the action is authorized to proceed.                                 |
| `proposal.rejected`  | An approver rejected the request.                                                                                 |
| `proposal.expired`   | The request reached its expiration window without completing the required approvals and was closed automatically. |
| `proposal.cancelled` | The initiator withdrew their own pending request before a decision was reached.                                   |

Each event's `payload` might carry the following fields:

| Field       | Type   | Required | Description                                                   |
| ----------- | ------ | -------- | ------------------------------------------------------------- |
| `action`    | string | Yes      | The governed action the proposal concerns.                    |
| `kind`      | string | No       | Proposal kind: `PROPOSAL`, `POLICY_CHANGE`, or `LIST_CHANGE`. |
| `policy_id` | string | No       | Identifier of the related policy.                             |

#### Policy change events

State-change events recorded across the lifecycle of a policy change. Actor is
`USER` or `SYSTEM`. These populate `oldValues` and `newValues` (see the
[example state-change event](#example-state-change-event)).

| Event type                | Recorded when                                                                |
| ------------------------- | ---------------------------------------------------------------------------- |
| `policy.change_requested` | A policy create, revision, or delete was submitted and is awaiting approval. |
| `policy.applied`          | An approved policy change took effect.                                       |

Each event's `payload` might carry the following fields:

| Field                 | Type   | Required | Description                                              |
| --------------------- | ------ | -------- | -------------------------------------------------------- |
| `action`              | string | Yes      | The policy action being performed.                       |
| `operation`           | string | Yes      | Operation applied: `ACTIVATE`, `SUPERSEDE`, or `DELETE`. |
| `scope`               | string | Yes      | Scope: `RESOURCE`, `GROUP`, or `WILDCARD`.               |
| `policy_lookup_key`   | string | No       | Lookup key of the affected policy.                       |
| `previous_version_id` | string | No       | Identifier of the prior policy version.                  |
| `proposal_id`         | string | No       | Identifier of the driving proposal.                      |