> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getimmutable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List Events

> Query audit log events with filtering and cursor pagination.

## GET /api/v1/events

Retrieve a paginated list of events with optional filters.

### Query Parameters

<ParamField query="action" type="string">
  Filter by action.
</ParamField>

<ParamField query="actor_id" type="string">
  Filter by actor identifier.
</ParamField>

<ParamField query="resource" type="string">
  Filter by resource type.
</ParamField>

<ParamField query="resource_id" type="string">
  Filter by primary resource identifier.
</ParamField>

<ParamField query="tenant_id" type="string">
  Filter by tenant identifier.
</ParamField>

<ParamField query="session_id" type="string">
  Filter by session identifier.
</ParamField>

<ParamField query="search" type="string">
  Case-insensitive search across actor name, action, resource name, and metadata. Uses PostgreSQL `ilike`.
</ParamField>

<ParamField query="target_type" type="string">
  Filter by target type.
</ParamField>

<ParamField query="target_id" type="string">
  Filter by target identifier.
</ParamField>

<ParamField query="from" type="string">
  ISO 8601 timestamp. Return events created at or after this time.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 timestamp. Return events created at or before this time.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Number of events per page (max 100).
</ParamField>

### Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```typescript JavaScript theme={null}
  const response = await client.getEvents({
    actor_id: "user_2hG9kLm",
    action: "document.*",
    from: "2026-03-01T00:00:00Z",
    limit: 10,
  });
  ```

  ```php Laravel theme={null}
  $response = AuditLog::getEvents([
      'actor_id' => 'user_2hG9kLm',
      'action' => 'document.*',
      'from' => '2026-03-01T00:00:00Z',
      'limit' => 10,
  ]);
  ```
</CodeGroup>

### Pagination

To iterate through all results:

```typescript theme={null}
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);
```