# List audit entries

`GET /audits`

- Base: `GET https://portal.watcheye.com.au/api/v1/audits`

Returns audit log entries for the calling account. Results are paginated.

The audit log records significant activity on your account: who did what, when, from
which IP, and against which resource. Use it to feed external SIEM / compliance systems,
to reconstruct an entity's history, or to surface activity in your own UI.

## Filters

The following filters can be applied via the `filter[...]` query parameters:

- `action` - exact action key (e.g. `created_watcheye_entity`)
- `action_type` - optional action sub-type (e.g. `password` for `login`)
- `user_uuid` - only actions performed by the given user
- `api_key_uuid` - only actions performed by the given API key
- `entity_uuid` - only actions associated with the given entity (covers direct entity actions plus actions on related resources like checks, events, and notes)
- `created_at_from` - inclusive lower bound on the audit timestamp (ISO 8601)
- `created_at_to` - inclusive upper bound on the audit timestamp (ISO 8601)

UUID-targeted filters return an empty page when the target uuid does not exist on the
calling account.

## Sorting

The `sort` query parameter accepts `created_at` (default: `-created_at`, newest first).
Prefix with `-` for descending order.

## Properties

The list endpoint does not return the per-audit `properties` object. Properties for some
actions can be many kilobytes, which would balloon page payloads. Use the
[show](/docs/reference/audit.show) endpoint to retrieve the full properties for a single
audit entry.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `page` | query | integer | The page of results to return, starting at 1. Example: `1` |
| `per_page` | query | integer | The number of audit entries per page (defaults to 30, max 500) Example: `30` |
| `filter[action]` | query | string | Exact action key Example: `created_watcheye_entity` |
| `filter[action_type]` | query | string | Only audit entries of the given action type. Example: `password` |
| `filter[user_uuid]` | query | string (uuid) | Only audit entries performed by the given portal user. |
| `filter[api_key_uuid]` | query | string (uuid) | Only audit entries performed by the given API key. |
| `filter[entity_uuid]` | query | string (uuid) | Only records for the given entity. |
| `filter[created_at_from]` | query | string (date-time) | Inclusive lower bound on `created_at` (ISO 8601). Example: `2025-01-01T00:00:00Z` |
| `filter[created_at_to]` | query | string (date-time) | Inclusive upper bound on `created_at` (ISO 8601). Example: `2025-12-31T23:59:59Z` |
| `sort` | query | string | Field to sort by; prefix with `-` for descending order Enum: `created_at`, `-created_at` Example: `-created_at` |

## Responses

### 200 Audit list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of audit entries |
| `data[].uuid` | string (uuid) | The audit entry's UUID Example: `5e1c0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].action` | string | Machine-readable action key. Use this for programmatic logic (filtering, branching). Example values include `created_watcheye_entity`, `updated_watcheye_entity`, `login`, `created_api_key`. Example: `created_watcheye_entity` |
| `data[].action_label` | string | Human-readable label for the action, suitable for display in UIs. Derived from the machine action key and is stable per action. Example: `Entity created` |
| `data[].action_type` | string or null | Optional sub-type qualifying the action. Used for actions that have meaningful variants (e.g. `login` -> `password` / `saml`, `login_failed` -> `password_incorrect` / `user_does_not_exist`). `null` for actions without sub-types. Example: `password` |
| `data[].description` | string | Human-readable description recorded at the time the audit was created. For most actions this is the action label; for some it includes additional context (e.g. the name of the resource touched). Example: `Entity created` |
| `data[].client_ip_address` | string or null | The IP address the action originated from, where one was captured. `null` for actions performed by the system. Example: `203.0.113.42` |
| `data[].agent` | object | Who performed the action. Always present; `name` and `uuid` are populated where the agent identity is available, and are `null` for system-initiated actions or where the agent record is no longer available. |
| `data[].agent.type` | string | * `user` - a user performed the action * `api_key` - an API key performed the action * `system` - the system performed the action (no agent identity) Enum: `user`, `api_key`, `system` Example: `user` |
| `data[].agent.uuid` | string (uuid) or null | UUID of the user or API key, or `null` when not available. Example: `11111111-2222-3333-4444-555555555555` |
| `data[].agent.name` | string or null | Display name of the agent: a user's full name (or username if no name is set), or the API key's label. `null` when the agent is the system or the agent record is no longer available. Example: `Jane Doe` |
| `data[].subject` | object or null | The resource the action was performed on. `null` when the audit has no specific subject (e.g. `login`). `uuid` is `null` when the subject record is no longer available. |
| `data[].subject.type` | string | Identifies the resource type for this audit's subject. Use it together with `uuid` to deep-link back to the resource via the matching API endpoint. Common values include `watcheyeEntity`, `watcheyeProgram`, `watcheyeNote`, `watcheyeEvent`, `watcheyeCheck`, `user`, and `api_key`. Example: `watcheyeEntity` |
| `data[].subject.uuid` | string (uuid) or null | UUID of the subject resource, or `null` when not available. Example: `123e4567-e89b-12d3-a456-426614174000` |
| `data[].created_at` | string (date-time) | ISO 8601 timestamp at which the audited action occurred Example: `2025-01-01T00:00:00Z` |
| `meta` | object |  |
| `meta.current_page` | integer | Example: `1` |
| `meta.per_page` | integer | Example: `30` |
| `meta.total` | integer | Example: `1` |
| `meta.last_page` | integer | Example: `1` |
| `api_reference` | string (uuid) |  |

**Sample response**

```json
{
    "data": [
        {
            "uuid": "5e1c0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
            "action": "created_watcheye_entity",
            "action_label": "Entity created",
            "action_type": "password",
            "description": "Entity created",
            "client_ip_address": "203.0.113.42",
            "agent": {
                "type": "user",
                "uuid": "11111111-2222-3333-4444-555555555555",
                "name": "Jane Doe"
            },
            "subject": {
                "type": "watcheyeEntity",
                "uuid": "123e4567-e89b-12d3-a456-426614174000"
            },
            "created_at": "2025-01-01T00:00:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 30,
        "total": 1,
        "last_page": 1
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

Standard error responses: 400, 401, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))