Access Events Resource

Table of Contents

• Overview

• List Access Events

• Event fields

• Summary events

• Pagination

  • Collecting events continuously

• Time ranges

• Event types

  • Authentication
  • Administrative changes
  • Data access

• Retention

• Rate limits

Overview

The access events resource exports your organization’s audit log as structured JSON, so a SIEM, data lake or other tool can collect it automatically, without anyone opening the web app.

Each event records who acted (the member or system, and the source IP address), what they did, where (the organization and the member or resource affected), when (a UTC timestamp) and the result (whether it succeeded, failed or was blocked, and why).

List Access Events

Fetch a page of access events for an organization, newest first by default.

{
  "code": "SUCCESS",
  "data": [
    {
      "_id": "66e2f1a4c3b2a10012ab34cd",
      "createdAt": "2026-09-15T14:03:22.114Z",
      "organization": "5f2a9c7e1b4d3a0011223344",
      "action": "user.login.blocked",
      "category": "authentication",
      "status": "blocked",
      "reason": "sso-required",
      "actor": {
        "type": "user",
        "userId": "5f2a9c7e1b4d3a0011990011",
        "email": "member@example.com",
        "ipAddress": "203.0.113.4",
        "channel": "app",
        "credentialId": null
      },
      "target": {
        "type": "user",
        "userId": "5f2a9c7e1b4d3a0011990011",
        "email": "member@example.com",
        "resourceId": null,
        "name": null
      },
      "aggregation": null,
      "details": {
        "method": "local"
      }
    }
  ],
  "pagination": {
    "count": 1,
    "hasMore": true,
    "nextCursor": "eyJ0IjoiMjAyNi0wOS0xNVQxNDowMzoyMi4xMTRaIi..."
  }
}

Invalid parameters (an unrecognized value, a count outside 1–1000, a malformed date or cursor, a cursor used with a different order, or a parameter given more than once) return a VALIDATION_ERROR. See Errors.

Event fields

Every event has the same fields. A field that doesn’t apply to an event is null, never missing.

These fields answer the "who, what, where, when and result" questions an audit review asks:

Summary events

Some actions can repeat many times a minute: a CI pipeline reading your tests, or a client retrying from a blocked address. These are recorded as summaries. A summary stands for every matching occurrence in a five-minute window: the same action, person or credential, IP address, kind of target, result and reason (and, for reads, the same endpoint). Nothing is sampled: aggregation.eventCount counts every occurrence. Any event with an aggregation object is a summary.

Every other action is recorded individually, so its aggregation is null. Older events only: an event recorded before summaries were introduced may be individual, with aggregation set to null, even if its action is listed above.

{
  "action": "data.read.summary",
  "category": "data_access",
  "status": "success",
  "aggregation": {
    "eventCount": 4,
    "windowStart": "2026-09-15T14:00:00.000Z",
    "windowEnd": "2026-09-15T14:05:00.000Z",
    "resourceIds": ["66e2f1a4c3b2a10012ab34ce"],
    "resourceIdsTruncated": false
  }
}

A summary appears as soon as its first occurrence is recorded, and its count keeps growing until about a minute after aggregation.windowEnd. Following a cursor doesn’t return an event twice, so a collector that reads a summary before then keeps the lower count. To store final counts, see Collecting events continuously.

Pagination

Results are paged with a cursor. Every response includes a pagination object:

• count: the number of events in this response.
• hasMore: true if more events match right now.
• nextCursor: the position just after the last event returned. Pass it as cursor to get the next page.

The order is fixed: by time, with ties broken consistently. Following nextCursor therefore returns every matching event exactly once, even while new events are being recorded. Don’t page by adjusting createdAfter or createdBefore yourself; events that share a timestamp can be skipped or repeated that way.

A cursor belongs to the order it was returned for: using it with the other order returns a VALIDATION_ERROR, because it would walk back over events you already have.

nextCursor is returned on the last page too, and a request with no new events hands the same cursor back. Save it and your next request picks up exactly where the last one stopped.

Collecting events continuously

To feed a SIEM or data lake, poll oldest-first:

1. First run: request order=asc with createdAfter set to the earliest time you want, for example 2026-01-01. Leave it out to start from the beginning of your organization’s log.
2. Keep requesting with cursor set to the latest nextCursor until hasMore is false.
3. Save the latest nextCursor.
4. Every following run (for example, every 5 minutes): request order=asc&cursor=<saved cursor>, then repeat steps 2–3.

To store final counts for summary events, add createdBefore set to about 10 minutes ago on every request, so a summary is only collected once its window has closed. Keep the same saved cursor.

curl -G "https://api.ghostinspector.com/v1/organizations/$ORG_ID/access-events" \
  -d "apiKey=$API_KEY" \
  -d "order=asc" \
  -d "count=1000" \
  --data-urlencode "cursor=$CURSOR"

import requests

URL = f"https://api.ghostinspector.com/v1/organizations/{org_id}/access-events"

def collect(cursor=None):
    """Return every event after `cursor`, and the cursor to save for the next run."""
    events = []
    while True:
        params = {"apiKey": api_key, "order": "asc", "count": 1000}
        if cursor:
            params["cursor"] = cursor
        body = requests.get(URL, params=params, timeout=30).json()
        if body["code"] != "SUCCESS":
            raise RuntimeError(body["message"])
        events.extend(body["data"])
        cursor = body["pagination"]["nextCursor"]
        if not body["pagination"]["hasMore"]:
            return events, cursor

events, cursor = collect(saved_cursor)  # saved_cursor is None on the first run
send_to_siem(events)
save(cursor)

Time ranges

createdAfter and createdBefore are inclusive and accept:

• a date, such as 2026-09-01, meaning midnight UTC at the start of that day, or
• a date and time with Z or a UTC offset, such as 2026-09-01T14:00:00Z or 2026-09-01T16:00:00+02:00.

A date and time without Z or an offset is rejected, because it would be ambiguous. All timestamps in responses are UTC.

Because a date means the start of that day, createdBefore=2026-06-30 leaves out June 30 itself. To include all of June 30, use createdBefore=2026-06-30T23:59:59.999Z.

Event types

These actions are recorded today, grouped by category. An action’s usual status is shown here; a few actions can record a different one, so always read status from the event.

Authentication

Administrative changes

Data access

A data read that is refused, such as someone outside your organization requesting one of your tests, is recorded in your organization with status set to blocked.

Retention

Access events are kept for as long as your organization exists. They aren’t affected by your plan’s test result retention period, and the full history is available through this endpoint.

Rate limits

Requests count toward the standard API rate limits. A page of up to 1,000 events is one request, so even a busy organization can be collected every few minutes well within the limits.