List audit events — StatusDashboard Docs

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 for the value on your org.

Request

See API Basics 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.

Sample request

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

Sample response

Status: 200 OK

{
  "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.

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.
`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 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.

On this page