---
title: "Look up events"
description: "Find Trails events by time, source, operation, caller, resource or error, in the console, the CLI or the API."
---

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

# Look up events

Looking up events returns your organization's events newest first, filtered by exact values.
You need the `audit.events.list` permission. For counts, groupings or conditions that the filters
don't cover, use [Trails Query](/trails/query).

Every lookup and every single-event read is itself recorded in Trails as a `LookupEvents` or
`GetEvent` event from `trails.ezghcloud.com`.

### Console

1. In the [console](https://console.ezghcloud.com), open **Trails**. The **Event history** tab
lists the events of your current organization.
2. Narrow the list with the filters above it:
- **Time range**: **Last hour**, **Last 24 hours**, **Last 7 days** (the default) or
**Last 30 days**.
- **Read-only**: **Changes** (the default), **Reads**, or **Changes and reads**.
- **Event source**: one API namespace, or **All event sources**.
- **Result**: **Any result**, **Errors only** or **Without errors**.
- A lookup attribute: choose **Event name**, **User ID**, **API key ID**, **Resource name**
or **Error code**, type a value, and press Enter.
3. Select **Load more** to see older events. **Clear filters** resets the list.
4. Select an event's name to open it. The event page shows who made the call, the credential,
source IP address, error, and the **Resources** it touched. **Event record** is the full
event as JSON.

On an event page, select the user to list all of that user's events, or a resource name to list
every event that touched the resource. Filters are kept in the page's URL, so you can share a
filtered view.
### CLI

```sh
ezgh trails events --from 2h --event-source iam.ezghcloud.com --read-only=false
ezgh trails events --principal ada@example.com --has-error
ezgh trails events --resource 'ezgh::org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2' --all -o json
ezgh trails events get 0199a3d0-3c4d-7e5f-a061-7c8d9e0f1a2b
```

| Flag | Filters to |
| --- | --- |
| `--from`, `--to` | Events at or after `--from` and before `--to`. Without `--from`, the last 7 days. |
| `--event-source` | One event source, such as `ocr.ezghcloud.com` |
| `--event-name` | One operation, such as `DeleteProject` |
| `--event-type` | `ApiCall`, `ServiceEvent` or `SignIn` |
| `--principal` | One caller: a principal ID, a user's email address, or a bot (`bot:<name>` or its slug) |
| `--access-key` | Calls made with one API key ID |
| `--resource` | Events that touched one resource name |
| `--error-code` | Calls that failed with one error code |
| `--read-only` | `true` for reads only, `false` for changes only |
| `--has-error` | `true` for failed calls only, `false` for successful calls only |
| `--project` | One project, by ID, slug or name |
| `--limit` | Events per page, 1 to 200 (default 50) |
| `--all` | Follow every page |
| `--cursor` | Start from a previous page's `nextCursor` |

Times are RFC 3339 (`2026-09-28T10:00:00Z`), a date (`2026-09-28`, midnight UTC), or a
duration ago (`15m`, `2h`, `7d`, `1w`).
### API

Call [LookupEvents](/trails-api/events/LookupEvents/):

```sh
curl -H "Authorization: Bearer $EZGH_API_KEY" \
  "https://audit.ezghcloud.com/v1/organizations/$ORG_ID/events?eventSource=iam.ezghcloud.com&readOnly=false&limit=50"
```

The response is `{ "events": [...], "nextCursor": ... }`. Each item in `events` is a full
event (see [Event format](/trails/events)). To read the next
page, send the same filters with `cursor` set to `nextCursor`. `nextCursor` is `null` on the
last page.

To read one event, call [GetEvent](/trails-api/events/GetEvent/):

```sh
curl -H "Authorization: Bearer $EZGH_API_KEY" \
  "https://audit.ezghcloud.com/v1/organizations/$ORG_ID/events/$EVENT_ID"
```

## Lookup parameters

All parameters are optional and combine with AND. Empty values are ignored. An unknown
parameter is refused with `400 invalid_request`.

| Parameter | Matches |
| --- | --- |
| `from` | Events at or after this time (RFC 3339). Default: 7 days ago. |
| `to` | Events before this time (RFC 3339). Must be after `from`. |
| `eventSource` | `eventSource` exactly |
| `eventName` | `eventName` exactly |
| `eventType` | `ApiCall`, `ServiceEvent` or `SignIn` |
| `readOnly` | `true` or `false` |
| `projectId` | Events about one project (a project ID) |
| `principalId` | `userIdentity.principalId` exactly |
| `accessKeyId` | `userIdentity.accessKeyId` exactly |
| `resourceName` | Events with this resource name in `resources` |
| `errorCode` | `errorCode` exactly |
| `hasError` | `true` for events with an `errorCode`, `false` for events without one |
| `limit` | Events per page, 1 to 200. Default 50. |
| `cursor` | The previous page's `nextCursor` |

## Limits and errors

A cursor works only with the organization and filters it came from; `limit` can change between
pages. Each lookup can read up to 20 million events and run for up to 5 seconds. A lookup past
either limit fails with `400 lookup_too_broad`: narrow the time range or add filters.

| Status | Code | Cause |
| --- | --- | --- |
| `400` | `invalid_request` | An unknown parameter, a malformed value, or `from` not before `to` |
| `400` | `invalid_cursor` | A cursor from another organization, from other filters, or edited |
| `400` | `lookup_too_broad` | The lookup read too many events |
| `401` | `unauthenticated` | Missing or invalid credentials |
| `403` | `access_denied` | The caller lacks `audit.events.list` |
| `404` | `not_found` | The organization, or for GetEvent the event, doesn't exist or you can't see it |
| `429` | `too_many_requests` | Too many requests; retry after the `Retry-After` header's seconds |
| `503` | `unavailable` | A dependency is unavailable; retry after the `Retry-After` header's seconds |

Source: https://docs.ezghcloud.com/trails/lookup/index.mdx