Skip to content

Getting started

Overview

This guide explains how to use the Audit Events API. After reading this guide, you should be able to retrieve audit events and filter them by date range, actor, IP address, and resource owner.

Pre-requisites

You must have a set of API credentials (service principal) to be able to call the Audit Events API. For more information refer to the appropriate quick start guide:

The logs_reports:read permission is required to retrieve audit events.

Making API requests

You can make the API calls in the next few sections using cURL. Follow the instructions on cURL's website to install this tool.

When using curl, a request to the Audit Events API has the following general form:

curl -X <method> -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" https://api.central.sophos.com/<path>

The command includes the following placeholders:

  • <method>: The request method. For the Audit Events API, this is GET.
  • <jwt>: The JWT access token returned when the IDP authenticates the service principal.
  • <tenant-id>: The ID of the tenant you want to query.
  • <path>: The request path for the API operation, for example audit/v1/audit-events.

The API descriptions in this guide only specify the request method and path. For example:

GET /audit/v1/audit-events

All API requests return HTTP status code 200 when successful.

Audit event operations

Get audit events

To get a page of audit events for a tenant, call:

GET /audit/v1/audit-events?startDate=2026-05-01T00:00:00.000Z

where startDate is an ISO-8601 formatted date string. This query parameter is required on all requests for this API.

Response: This returns a paginated list of audit events.

{
  "items": [
    {
      "id": "4e3b2978-9843-4891-6548-4d991d8c0fbc",
      "occurredAt": "2026-05-20T17:39:24.480Z",
      "modifiedBy": "john.doe@example.com",
      "itemType": "AUTHENTICATION",
      "itemModified": "john.doe@example.com",
      "description": "SUCCESSFUL_AUTHENTICATION",
      "originIpAddress": "195.171.192.19",
      "resourceOwnerId": "86974568-3620-4a81-8bd7-e127af39b494",
      "resourceOwnerType": "TENANT",
      "modifierType": "TENANT_ADMIN",
      "modifierAccountId": "5c487584-9cfc-4de1-bd71-dcc0189a1810",
      "modifierAccountType": "Customer"
    }
  ],
  "pages": {
    "fromKey": "58fd4443-3b28-4206-92e8-8e07065e85b7",
    "nextKey": "edd7fa83-2733-47b2-b51a-634236cc8a2f",
    "size": 100,
    "maxSize": 500
  }
}

Each audit event includes the following fields:

Field Description
id Unique identifier for the audit event.
occurredAt When the event occurred (ISO 8601 format).
modifiedBy Identifier of the actor that performed the action (for example, an email address).
itemType Type of item modified; corresponds to the Item Type in audit reports.
itemModified Identifier of the item that was modified.
description Description of the audit event.
originIpAddress IP address associated with the event.
resourceOwnerId Identifier of the resource owner.
resourceOwnerType Type of the resource owner for the audited item.
modifierType Category of the actor that performed the modification.
modifierAccountId Account identifier of the modifier.
modifierAccountType Account type for the modifier.

Filter audit events

You can narrow results by appending one or more query parameters to the request. The startDate parameter is required - all the others are optional.

Parameter Description
startDate Return only events that occurred on or after this date-time (ISO 8601). The startDate must be within 90 days of the current date.
endDate Return only events that occurred strictly before this date-time (ISO 8601).
originIpAddress Return only events that originated from this IP address.
modifiedBy Return only events performed by this actor (for example, an email address).
modifierAccountId Return only events from this modifier account ID.
resourceOwnerId Return only events associated with this resource owner ID.
pageFromKey Key to fetch the next page of results (use the nextKey from a prior response).
pageSize Maximum number of events to return per page (up to 500).

For example, to retrieve audit events for a specific user within a date range, call:

GET /audit/v1/audit-events?startDate=2026-05-01T00:00:00.000Z&endDate=2026-05-31T23:59:59.999Z&modifiedBy=john.doe%40example.com

Response: A filtered, paginated list of matching audit events.

{
  "items": [
    {
      "id": "4e3b2978-ab6c-4891-9a7d-4d991d8c0fbc",
      "occurredAt": "2026-05-20T17:39:24.480Z",
      "modifiedBy": "john.doe@example.com",
      "itemType": "AUTHENTICATION",
      "itemModified": "john.doe@example.com",
      "description": "SUCCESSFUL_AUTHENTICATION",
      "originIpAddress": "195.171.192.19",
      "resourceOwnerId": "47fca5ed-3620-4a81-8bd7-e127af39b494",
      "resourceOwnerType": "TENANT",
      "modifierType": "TENANT_ADMIN",
      "modifierAccountId": "5c487584-9cfc-4de1-bd71-dcc0189a1810",
      "modifierAccountType": "Customer"
    }
  ],
  "pages": {
    "size": 100,
    "maxSize": 500
  }
}

Fetch successive pages

The Audit Events API uses cursor-based pagination. Each response includes a pages object; when there are more results, it includes the following keys to drive page navigation:

Key Description
nextKey Cursor pointing to the next page of results. Absent when there are no more pages.
fromKey Cursor that marks the start of the current page; can be used to re-fetch the same page.

To page through all events, repeat the same request and pass the previous response's nextKey as the pageFromKey query parameter. Stop when nextKey is absent from the response.

Page 1 — first request (no pageFromKey):

GET /audit/v1/audit-events?startDate=2026-05-01T00:00:00.000Z&pageSize=100

Response:

{
  "items": [ ... ],
  "pages": {
    "fromKey": "58fd4443-3b28-4206-92e8-8e07065e85b7",
    "nextKey": "edd7fa83-2733-47b2-b51a-634236cc8a2f",
    "size": 100,
    "maxSize": 500
  }
}

Page 2 — pass nextKey from page 1 as pageFromKey:

GET /audit/v1/audit-events?startDate=2026-05-01T00:00:00.000Z&pageSize=100&pageFromKey=edd7fa83-2733-47b2-b51a-634236cc8a2f

Response:

{
  "items": [ ... ],
  "pages": {
    "fromKey": "edd7fa83-2733-47b2-b51a-634236cc8a2f",
    "nextKey": "a1c3e572-91d4-48b3-bf6e-3f2209aa7d01",
    "size": 100,
    "maxSize": 500
  }
}

Last page — when nextKey is absent, all events have been retrieved:

{
  "items": [ ... ],
  "pages": {
    "fromKey": "a1c3e572-91d4-48b3-bf6e-3f2209aa7d01",
    "size": 100,
    "maxSize": 500
  }
}

Any filters applied to the first request (such as startDate, endDate, or modifiedBy) must be included on every subsequent page request to keep the result set consistent.

Conclusion

For a comprehensive description of the Audit Events API, see API reference.