List Audit Log Events — AuditRails API Reference

The List Events endpoint returns your audit log entries in descending order by log_id, giving you the most recent activity first. You can narrow results with any combination of filters and page through large result sets using the cursor returned in each response. Every response includes an X-Request-Id header you can use when tracing requests with AuditRails support.

Endpoint

GET https://api.auditrails.io/v1/events

Query Parameters

string

Filter events to an exact action name, such as user.login or document.deleted. Partial matches are not supported — the value must be an exact string match.

string

Return only events produced by this actor. Must be an exact match against the actor_id field stored on each event.

string

Filter to events targeting a specific resource identifier, for example session/sess_abc. Must be an exact match.

string

Inclusive start date in YYYY-MM-DD format. Events with a timestamp on or after midnight UTC of this date are included.

string

Inclusive end date in YYYY-MM-DD format. Events with a timestamp before the end of this day (UTC) are included.

string

Pagination cursor. Pass the next_cursor value from the previous response to fetch the next page of results. Omit this parameter to start from the most recent event.

integer

default:"50"

Number of events to return per page. Minimum 1, maximum 100. Any value outside this range is silently clamped back to the default of 50.

Response Fields

array

required

Ordered array of event objects, newest first.

Show Event object fields

string

Unique ULID identifier for this event. Monotonically increasing, making it safe to use as a sort key.

string

The organization identifier that owns this event.

string

The project within the organization that this event belongs to.

integer

Version of the event schema used when the event was recorded.

string

The action name that was logged, for example user.login or file.download.

string

Identifier of the actor who performed the action.

string

Semantic type of the actor, for example user, service, or system. Present when supplied at ingestion.

string

The resource that was acted upon, such as session/sess_abc.

string

Semantic type of the resource, for example session or document. Present when supplied at ingestion.

string

High-level grouping for the action, for example auth or data_access. Derived from the action catalog.

string

Severity level of the event, for example info, warning, or critical. Present when supplied at ingestion or set by the action catalog.

string

Session identifier linked to this event. Present when supplied at ingestion.

string

Client-supplied timestamp in ISO 8601 format. Distinct from timestamp, which is set server-side at ingestion. Present when supplied at ingestion.

object

Arbitrary key-value payload attached when the event was ingested. Contents vary by action type.

string

ISO 8601 timestamp (UTC) recorded at ingestion time, for example 2025-01-15T10:30:00.123Z.

string

IP address associated with the event, if provided at ingestion.

string

Two-letter ISO country code resolved from ip_address, for example US.

string

City name resolved from ip_address, for example San Francisco.

string

SHA-256 hash of this event’s canonical payload. Forms part of the tamper-evident hash chain.

string

SHA-256 hash of the immediately preceding event. Links this event into the chain.

integer

Sequential position of this event in the project’s hash chain.

string

Opaque cursor to pass as the cursor parameter on your next request. Only present when has_more is true.

boolean

required

true when additional pages of results exist beyond the current response.

The response does not include a total count field. Because audit logs can grow very large, computing an exact total on every request would be prohibitively slow. Use has_more and the cursor to determine whether more results exist.

Example Request

curl -G https://api.auditrails.io/v1/events \
  -H "Authorization: Bearer at_live_xxx" \
  -d "action=user.login" \
  -d "date_from=2025-01-01" \
  -d "date_to=2025-01-31" \
  -d "limit=10"

Example Response

{
  "events": [
    {
      "log_id": "01HX7YGBFZ3QK8N9VMJT5RPCE4",
      "tenant_id": "org_abc123",
      "project_id": "proj_def456",
      "schema_version": 1,
      "action": "user.login",
      "actor_id": "user_123",
      "resource": "session/sess_abc",
      "metadata": {
        "ip": "203.0.113.1",
        "method": "password"
      },
      "timestamp": "2025-01-15T10:30:00.123Z",
      "ip_address": "203.0.113.1",
      "country": "US",
      "city": "San Francisco",
      "hash": "a1b2c3...",
      "prev_hash": "9f8e7d...",
      "chain_seq": 4213
    }
  ],
  "next_cursor": "01HX7XKQT82FM4NPWRJ6DSCBA3",
  "has_more": true
}

Pagination

To page through a full result set, pass next_cursor from each response back as the cursor parameter on the next request. Repeat until has_more is false. All filter parameters must remain identical across pages — changing a filter mid-pagination produces undefined results.

# Page 1 — no cursor
curl -G https://api.auditrails.io/v1/events \
  -H "Authorization: Bearer at_live_xxx" \
  -d "actor_id=user_123" \
  -d "limit=100"

# Page 2 — pass next_cursor from page 1
curl -G https://api.auditrails.io/v1/events \
  -H "Authorization: Bearer at_live_xxx" \
  -d "actor_id=user_123" \
  -d "limit=100" \
  -d "cursor=01HX7XKQT82FM4NPWRJ6DSCBA3"

Error Responses

Status	Code	Description
`401`	`auth/key_not_found`	The API key provided in the `Authorization` header is missing or invalid.
`500`	`read/query_failed`	An internal error occurred while querying the event log. Retry with exponential backoff.

Overview

Ingestion

Read & Verify

Data Subject Requests

List Audit Log Events — AuditRails API Reference

Endpoint

Query Parameters

Response Fields

Example Request

Example Response

Error Responses

​Endpoint

​Query Parameters

​Response Fields

​Example Request

​Example Response

​Pagination

​Error Responses

Endpoint

Query Parameters

Response Fields

Example Request

Example Response

Pagination

Error Responses