Audit Log API

The audit log API returns an organization’s audit log events, oldest first, as JSON. A client polls it on an interval and reads on from where it left off using a cursor. This is the shape most SIEM HTTP pull inputs (Splunk, Microsoft Sentinel, Elastic, Datadog, …) expect.

For a step-by-step setup, see Ingest the Audit Log into a SIEM.

Endpoint

GET https://api.graphql-hive.com/audit-log/v1/events

Authentication

Send an organization access token with the Describe audit log (auditLog:describe) permission as a bearer token:

Authorization: Bearer <access token>

Project and personal access tokens can’t be granted auditLog:describe and are rejected.

Query Parameters

Response

A successful request returns status 200 with a page of events:

{
  "events": [
    {
      "version": 1,
      "id": "9f5e3a1c-4d6b-4b9e-8f0a-2c7d1e6b5a43",
      "timestamp": "2026-11-02T10:00:00Z",
      "eventType": "USER_INVITED",
      "organization": { "id": "4f2a5c0e-1b3d-4e6f-9a8b-7c6d5e4f3a2b" },
      "actor": {
        "type": "user",
        "user": { "id": "0d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a", "email": "admin@example.com" },
        "accessToken": null,
        "ipAddress": "203.0.113.42",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
      },
      "metadata": {
        "inviteeEmail": "new-member@example.com",
        "roleId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
      }
    }
  ],
  "nextCursor": "eyJ2IjoxLCJ0aW1lc3RhbXAiOjE3OTM2MTM2MDAsImlkIjoiOWY1ZTNhMWMtNGQ2Yi00YjllLThmMGEtMmM3ZDFlNmI1YTQzIn0",
  "hasMore": false,
  "cursorExpired": false
}

Event Fields

New fields may be added to the event over time without changing version, so make sure your parser ignores fields it doesn’t know.

Pagination

Events are paginated with an opaque cursor. Without a cursor or since parameter, the first request starts at the beginning of the retention period (one year ago):

GET https://api.graphql-hive.com/audit-log/v1/events?limit=1000

To start at a specific point in time instead, for example when you don’t need the full year of history, pass since:

GET https://api.graphql-hive.com/audit-log/v1/events?since=2026-11-01T00:00:00Z&limit=1000

Every response contains a nextCursor. Pass it as cursor to get the next page:

GET https://api.graphql-hive.com/audit-log/v1/events?cursor=eyJ2IjoxLCJ0aW1lc3RhbXAiOjE3OTM2MTM2MDAsImlkIjoiOWY1ZTNhMWMtNGQ2Yi00YjllLThmMGEtMmM3ZDFlNmI1YTQzIn0&limit=1000

While hasMore is true, request the next page right away. Once hasMore is false, you’ve caught up: store the nextCursor and poll again later (e.g. every minute) with it. The cursor is returned on every page, including empty ones, so you can always persist the latest one.

When hasMore is true, the response also carries a Link header with the URL of the next page, for clients that follow links instead of reading the cursor from the body:

Link: </audit-log/v1/events?cursor=eyJ2IjoxLCJ0aW1lc3RhbXAiOjE3OTM2MTM2MDAsImlkIjoiOWY1ZTNhMWMtNGQ2Yi00YjllLThmMGEtMmM3ZDFlNmI1YTQzIn0&limit=1000>; rel="next"

Keep the same eventTypes filter for every request of a cursor.

Delivery Guarantees

• Ordering: events are returned oldest first, ordered by timestamp, then by id.
• At-least-once: in rare cases (e.g. a retried request) the same event can be returned more than once. Deduplicate on the event id.
• Retention: events are kept for one year. If your integration was offline for longer than that, the response reports cursorExpired: true and continues with the oldest event that’s still available.

Errors

Every non-2xx response has the same body:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The access token is missing the 'auditLog:describe' permission."
  }
}

Rate Limits

Requests are limited to 60 per minute per organization, shared by all access tokens of the organization. Polling once a minute and paging with limit=1000 while catching up stays well within this budget.

Event Types

The eventTypes parameter accepts the following values. New event types are added over time, so treat eventType as an open string rather than a fixed list.

For example, to only fetch sign in events:

GET https://api.graphql-hive.com/audit-log/v1/events?eventTypes=USER_SIGNED_IN,USER_SIGN_IN_FAILED