--- title: "Event format" description: "The fields of a Trails event, what each one holds, and an example." --- > 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. # Event format Each Trails event is a JSON object in the same shape wherever you read it: the console's **Event record**, [GetEvent](/trails-api/events/GetEvent/), [LookupEvents](/trails-api/events/LookupEvents/) and `ezgh trails events get -o json`. ## Example A bot creates an OCR processor with an API key: ```json { "eventVersion": "1.0", "eventId": "0199a3d0-3c4d-7e5f-a061-7c8d9e0f1a2b", "eventTime": "2026-09-28T09:58:02.114Z", "eventType": "ApiCall", "eventCategory": "Management", "eventSource": "ocr.ezghcloud.com", "eventName": "CreateProcessor", "readOnly": false, "region": "us-west-1", "organizationId": "0199a3c2-5b1e-7d40-9f3a-2c8e6b1d4f70", "projectId": "0199a3c2-6c2f-7e51-8a4b-3d9f7c2e5a81", "userIdentity": { "type": "Bot", "principalId": "0199a3c4-0d1e-7f20-8a3b-4c5d6e7f8091", "userName": "deployer", "isRoot": false, "accessKeyId": "0199a3c4-1e2f-7a31-9b4c-5d6e7f809102", "sessionContext": { "credential": "apiKey", "sessionIssuedAt": null, "ssoProviderId": null, "mfaAuthenticated": false, "clientId": null }, "invokedBy": null }, "sourceIpAddress": "203.0.113.9", "userAgent": "curl/8.7.1", "requestParameters": { "orgId": "0199a3c2-5b1e-7d40-9f3a-2c8e6b1d4f70", "projectId": "0199a3c2-6c2f-7e51-8a4b-3d9f7c2e5a81", "name": "Receipts", "model": "unlimited-ocr", "modelVersion": "latest", "languages": ["en"], "outputFormat": "text", "options": { "detail": "high" } }, "responseElements": { "id": "0199a3d0-2b3c-7d4e-9f50-6b7c8d9e0f1a", "slug": "prc_4k2m9x0a7qpe", "name": "Receipts", "resourceName": "ezgh:us-west-1:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:prc_4k2m9x0a7qpe" }, "additionalEventData": null, "errorCode": null, "errorMessage": null, "resources": [ { "resourceName": "ezgh::org_k3f9a0x2m7qp", "type": "Organization" }, { "resourceName": "ezgh::org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2", "type": "Project" }, { "resourceName": "ezgh:us-west-1:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:prc_4k2m9x0a7qpe", "type": "Processor" } ], "requestId": "0199a3d0-3b4c-7d5e-8f60-7a8b9c0d1e2f" } ``` A refused call has the same shape. These fields differ: `responseElements` is `null`, and `errorCode` and `errorMessage` hold the error the caller received. ```json { "responseElements": null, "errorCode": "access_denied", "errorMessage": "This API key isn't allowed to ocr.processors.create" } ``` ## Fields Every field is always present. Fields without a value are `null`. | Field | Type | Description | | --- | --- | --- | | `eventVersion` | string | The event format's version: `1.0`. | | `eventId` | string | The event's ID, a UUID. | | `eventTime` | string | When the request arrived, in UTC with milliseconds: `2026-09-28T09:58:02.114Z`. | | `eventType` | string | `ApiCall` for an API call, `SignIn` for sign-in and sign-out, `ServiceEvent` for a change the platform made on its own. | | `eventCategory` | string | `Management`. | | `eventSource` | string | The API namespace the call was made to, such as `iam.ezghcloud.com`. See [event sources](/trails#what-trails-records). | | `eventName` | string | The operation, such as `CreateApiKey` or `ProcessDocument`. | | `readOnly` | boolean | `true` when the request only read (`GET` or `HEAD`). | | `region` | string | The region that recorded the event: `us-west-1`. | | `organizationId` | string | The organization the event belongs to. | | `projectId` | string or null | The project the call was about, or `null` for organization-level calls. | | `userIdentity` | object | Who acted. See [userIdentity](#useridentity). | | `sourceIpAddress` | string or null | The caller's IP address, up to 64 characters. `null` for service events. | | `userAgent` | string or null | The caller's `User-Agent`, cut to 512 characters. | | `requestParameters` | object or null | The request's path parameters, query parameters and top-level body fields, with secrets hidden. `null` when the request had none. | | `responseElements` | object or null | For a successful write, the identifiers of what it created or changed: `id`, `slug`, `name`, `resourceName`, `prefix` and `expiresAt`, at the top level of the response or one object down, plus fields an operation adds. `null` for reads and failures. Never contains a token or secret. | | `additionalEventData` | object or null | Extra data an operation records, else `null`. | | `errorCode` | string or null | The error `code` the caller received, such as `access_denied`, up to 64 characters. `null` on success. | | `errorMessage` | string or null | The error `message` the caller received, up to 1,024 characters. `null` on success. | | `resources` | array | The resources the call touched, up to 50. Each is `{ "resourceName", "type" }`, where `type` is the resource type, such as `Organization`, `Project`, `Bot` or `Processor`. | | `requestId` | string or null | The request's ID, from its `X-Request-Id` header. | A whole event is at most 64 KiB. ### userIdentity | Field | Type | Description | | --- | --- | --- | | `type` | string | `Root` (the organization's root user), `User`, `Bot`, `EzghService` (the platform, for a service event) or `Unknown`. | | `principalId` | string or null | The user's or bot's ID. | | `userName` | string or null | The user's email address or the bot's name when the event happened. | | `isRoot` | boolean | Whether the caller is the organization's root user. | | `accessKeyId` | string or null | The ID of the API key used, or `null` if no API key was used. | | `sessionContext` | object or null | How the caller authenticated. `null` for service events. | | `sessionContext.credential` | string | `session` (signed in to the console), `apiKey` (an API key) or `oauth` (an OAuth access token, such as the `ezgh` CLI's). | | `sessionContext.sessionIssuedAt` | string or null | When the session or sign-in began, when known. | | `sessionContext.ssoProviderId` | string or null | The SSO identity provider used to sign in, if any. | | `sessionContext.mfaAuthenticated` | boolean | Whether the session used multi-factor authentication. | | `sessionContext.clientId` | string or null | For `oauth`, the OAuth client, such as `ezgh-cli`. `null` otherwise. | | `invokedBy` | string or null | For a service event, the API namespace that caused the change, such as `billing.ezghcloud.com`. | ## Hidden values In `requestParameters`, the value of any field whose name contains `token`, `secret`, `password`, `authorization`, `cookie`, `apikey`, `privatekey` or `credential` (in any case, at any depth) is replaced with `HIDDEN_DUE_TO_SECURITY_REASONS`. Operations also hide fields of their own, such as an OCR processor's `description` and `tags`. Values nested more than 6 levels deep become `"[truncated]"`, and arrays keep their first 100 items. Headers are never recorded. For `ProcessDocument`, `requestParameters` holds only the document's metadata: `pageCount` (the number of pages selected), `bytes` (the document's size), `mimeType` (its detected type) and `pages` (the page numbers selected). ## Resource names `resourceName` identifies a resource across EZGH Cloud. After `ezgh:` comes the region (empty for resources that aren't regional), then the slugs of the organization, project and resource: | Resource | Format | | --- | --- | | Organization | `ezgh::org_…` | | Project | `ezgh::org_…:prj_…` | | Organization-level resource, such as a bot | `ezgh::org_…:bot_…` | | Regional resource in a project, such as an OCR processor | `ezgh:us-west-1:org_…:prj_…:prc_…` | Filter by a resource name to see every event that touched it. See [Look up events](/trails/lookup). Source: https://docs.ezghcloud.com/trails/events/index.mdx