Skip to main content

​
GET /api/v1/events

Retrieve a paginated list of events with optional filters.

​
Query Parameters

​
action
string
Filter by action.
​
actor_id
string
Filter by actor identifier.
​
resource
string
Filter by resource type.
​
resource_id
string
Filter by primary resource identifier.
​
tenant_id
string
Filter by tenant identifier.
​
session_id
string
Filter by session identifier.
​
search
string
Case-insensitive search across actor name, action, resource name, and metadata. Uses PostgreSQL ilike.
​
target_type
string
Filter by target type.
​
target_id
string
Filter by target identifier.
​
from
string
ISO 8601 timestamp. Return events created at or after this time.
​
to
string
ISO 8601 timestamp. Return events created at or before this time.
​
cursor
string
Pagination cursor from a previous response.
​
limit
integer
default:"25"
Number of events per page (max 100).

​
Response

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "actor": {
        "id": "user_2hG9kLm",
        "name": "Sarah Chen",
        "type": "user"
      },
      "action": "document.created",
      "action_category": "documents",
      "resource": {
        "type": "document",
        "id": "doc_8nXpQr3",
        "name": "Q4 Financial Report"
      },
      "targets": [],
      "metadata": { "folder": "reports" },
      "tenant_id": "org_7rT2xBc",
      "session_id": "sess_4kN8pLm",
      "ip_country": "US",
      "ip_city": "San Francisco",
      "idempotency_key": null,
      "version": null,
      "integrity": {
        "event_hash": "a3f2c8d1e4b5...",
        "previous_event_hash": "7b9e1d3f5a2c..."
      },
      "occurred_at": "2026-03-15T14:32:18.847312Z",
      "created_at": "2026-03-15T14:32:18.847312Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0xNVQxNDozMjoxOC44NDczMTJaIn0",
    "total": 4821
  }
}

​
Examples

curl "https://getimmutable.dev/api/v1/events?actor_id=user_2hG9kLm&action=document.*&from=2026-03-01T00:00:00Z&limit=10" \
  -H "Authorization: Bearer imk_your_api_key_here"

​
Pagination

To iterate through all results: 
let cursor: string | undefined;
do {
  const page = await client.getEvents({ cursor, limit: 100 });
  for (const event of page.data) {
    process(event);
  }
  cursor = page.pagination.has_more ? page.pagination.next_cursor : undefined;
} while (cursor);