List audit events

GET /api/app/audit

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

Requires the admin role and the audit log feature entitlement (enabledFeatures.auditRetentionDays).

Request

See API Basics for required headers.

Query parameters

Parameter	Type	Required	Description
`startDate`	ISO 8601	No	Start of the time range. Defaults to 7 days ago.
`endDate`	ISO 8601	No	End of the time range. Defaults to now.
`actorEmail`	string	No	Filter events to a specific actor email address.
`limit`	integer	No	Maximum events per page. Default `100`, max `500`.
`nextToken`	string	No	Opaque pagination cursor from a previous response.

Sample request

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

Sample response

Status: 200 OK

{
  "events": [
    {
      "orgId": "a1b2c3d4-0000-4000-8000-e5f6a7b8c9d0",
      "createdAt": "2026-04-15T12:03:00.000Z",
      "actorEmail": "alice@acmeplumbing.com",
      "actorSub": "cognito-sub-uuid",
      "actorType": "user",
      "action": "user.invited",
      "resource": "USER#carol@acmeplumbing.com",
      "meta": { "roles": ["user"], "allowPasswordAuth": true, "sendInvitation": true },
      "ip": "203.0.113.42"
    }
  ],
  "nextToken": "eyJQSyI6Ik9SRyNhMWIyYzNkNCJ9"
}

nextToken is null when there are no further pages. Pass it as the nextToken query parameter to retrieve the next page. resource, meta, and ip are omitted when not recorded for an event.

Event actor types

`actorType`	Description
`user`	A human user authenticated via Cognito JWT.
`api_key`	A machine caller authenticated via an API key.
`system`	A background process (Cognito trigger, scheduled job, or queue worker).
`platform_admin`	A Recomly platform administrator.

Error responses

See API Basics for standard status codes and error response format.

Status	Meaning
`400`	Invalid query parameters.
`403`	Caller does not have the admin role, or the audit log feature is not enabled.