---
title: "Trails"
description: "Trails records the API activity in your organization as audit events you can look up and query with SQL."
---

> 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.

# Trails

Trails is your organization's audit log. Each call made to an EZGH Cloud public API in your
organization, and each change the platform makes to your resources, is recorded as an event:
who acted, from where, with which credential, on which resources, and whether it succeeded.
You can browse and filter events in the console, look them up with the API or the `ezgh` CLI,
and run SQL over them with Trails Query.

- [Event format](/trails/events) — Every field of a Trails event, with an example.
- [Look up events](/trails/lookup) — Filter events in the console, the CLI and the API.
- [Trails Query](/trails/query) — Run SQL over your events, asynchronously.

## What Trails records

Events come from these event sources:

| Event source | Activity |
| --- | --- |
| `organizations.ezghcloud.com` | Organizations and projects |
| `iam.ezghcloud.com` | Users, groups, bots, policies, API keys, invitations, SSO and SCIM settings |
| `signin.ezghcloud.com` | Sign-in, sign-out and account operations |
| `billing.ezghcloud.com` | Billing details, payment methods, invoices and costs |
| `ocr.ezghcloud.com` | OCR models, processors and document processing |
| `trails.ezghcloud.com` | Reading Trails and running Trails Query |

| Activity | Recorded |
| --- | --- |
| A call that changes something, whether it succeeds or fails | Yes (`readOnly: false`) |
| A call that only reads, such as `GetProcessor` or `LookupEvents` | Yes (`readOnly: true`) |
| A call refused because the caller lacks permission (`403 access_denied`) | Yes, with `errorCode` |
| A `400` error returned to a member of the organization | Yes, with `errorCode` |
| A change the platform makes to your resources on its own | Yes (`eventType: ServiceEvent`) |
| A request without valid credentials (`401`) | No |
| A request for an organization the caller doesn't belong to (`404`) | No |
| A write from a browser session refused by the Origin check | No |
| Polling a query's status (`GetQuery`) or reading the query schema (`GetQuerySchema`) | No |

An event is recorded only once the caller is known to be a member of the organization. Requests
that no one can be held to, and probes of organizations you don't belong to, don't appear in
anyone's Trails.

Trails never records passwords, tokens, cookies, client secrets or payment details. Request
fields that could hold a secret are replaced with `HIDDEN_DUE_TO_SECURITY_REASONS`. For document
processing, Trails records the page count, size and file type, never the document's content,
file name or extracted text.

## Retention

Trails doesn't expire events. Trails Query results are kept for 7 days after the query finishes.

## Who can use Trails

Trails is organization-wide. Access is controlled by these IAM actions:

| Action | Allows | In `AdministratorAccess` | In `ReadOnlyAccess` |
| --- | --- | --- | --- |
| `audit.events.list` | Look up events and read single events | Yes | Yes |
| `audit.queries.run` | Start Trails queries, and read the query schema | Yes | Yes |
| `audit.queries.get` | See your own queries' status and results | Yes | Yes |
| `audit.queries.list` | See everyone's queries and their results | Yes | Yes |
| `audit.queries.cancel` | Cancel queries you can see | Yes | No |

The root user can do all of these. API keys act with their owner's access. See [IAM](/iam) for
policies.

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