# List audit events

Retrieve paginated audit log events for the organization.

Source: https://statusdashboard.com/docs/api/security/audit/list

`GET /app/audit`

Returns a paginated list of audit events for the caller's organization, newest first.

Audit logging is **always enabled** for every organization. Access is controlled by org role — not by a plan feature toggle. Retention length is set by the `auditRetentionDays` plan limit (always at least **1** day); see [Get account](/docs/api/account-management/account/get) for the value on your org.

***

## Request
See [API Basics](/docs/api) for required headers.

### Query parameters
| Parameter    | Type    | Required | Description                                                                                             |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `startDate`  | string  | No       | ISO 8601 date string (`YYYY-MM-DD`). Start of the time range. Defaults to 7 days ago.                   |
| `endDate`    | string  | No       | ISO 8601 date string (`YYYY-MM-DD`). End of the time range. Defaults to now.                            |
| `actorEmail` | string  | No       | Filter events to an exact actor email address (case-insensitive). Must be a valid email when provided.  |
| `limit`      | integer | No       | Maximum events per page. Default `10`, max `100`. Paginated browsing only — not for bulk export.        |
| `nextToken`  | string  | No       | Next-page bookmark from the previous response — pass unchanged. See [Pagination](/docs/api#pagination). |

***

## Sample request
```bash
curl "https://api.statusdashboard.com/app/audit?limit=10&actorEmail=alice%40acmeplumbing.com" \
  -H "Authorization: Bearer bcf847abf5c6:def456"
```

## Sample response
**Status: `200 OK`**

```json
{
  "events": [
    {
      "createdAt": "2026-04-15T12:03:00.000Z",
      "actorEmail": "alice@acmeplumbing.com",
      "actorType": "user",
      "action": "user.invited",
      "resource": "USER#carol@acmeplumbing.com",
      "meta": { "roles": ["event"], "allowPasswordAuth": true, "sendInvitation": true },
      "ip": "203.0.113.42"
    }
  ],
  "nextToken": "eyJQSyI6Ik9SRyNhMWIyYzNkNCJ9"
}
```

***

## Response fields
| Field       | Type              | Description                                                                         |
| ----------- | ----------------- | ----------------------------------------------------------------------------------- |
| `events`    | array             | Audit events for this page, newest first.                                           |
| `nextToken` | string \| omitted | Next-page bookmark when more results exist. See [Pagination](/docs/api#pagination). |

### Audit event fields
Each `events[]` item:

| Field        | Type              | Description                                                                                                     |
| ------------ | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `createdAt`  | string            | ISO 8601 timestamp when the action occurred.                                                                    |
| `actorEmail` | string            | Email of the actor. Empty string for `platform_admin` events (tenants see **StatusDashboard Staff** in the UI). |
| `actorType`  | string            | One of `user`, `api_key`, `system`, or `platform_admin`. See [event actor types](#event-actor-types).           |
| `action`     | string            | Action identifier (e.g. `user.invited`, `dashboard.updated`).                                                   |
| `resource`   | string \| omitted | Resource identifier (e.g. `USER#email@example.com`). Omitted when not recorded.                                 |
| `meta`       | object \| omitted | Additional context for the action. Omitted when not recorded.                                                   |
| `ip`         | string \| omitted | Client IP when recorded. Omitted when not recorded.                                                             |

### Event actor types
| `actorType`      | Description                                                               |
| ---------------- | ------------------------------------------------------------------------- |
| `user`           | A human user authenticated via a StatusDashboard session.                 |
| `api_key`        | A machine caller authenticated via an API key.                            |
| `system`         | A background process (automated trigger, scheduled job, or queue worker). |
| `platform_admin` | A StatusDashboard platform administrator.                                 |

For `platform_admin` events, `actorEmail` is always returned as an empty string. Tenants see a **StatusDashboard Staff** badge in the dashboard; internal platform-admin views retain the real email.

***

## Pagination
See [Pagination](/docs/api#pagination) in API Basics. Re-send the same query parameters on every page request.

`resource`, `meta`, and `ip` are omitted from each event when not recorded.

***

## Error responses
| Status | When                                                                                                                                                                                            |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid query parameters.                                                                                                                                                                       |
| `403`  | Caller is not an org **admin**, org membership is disabled, or the organization is **suspended**. Audit logging itself is always on — this status does not mean audit is disabled on your plan. |
| `500`  | Internal server error.                                                                                                                                                                          |