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

# Event Log

> The status events Control Plane records against a resource: deduplication, fields, and how to list them by CLI or API.

An event log entry is generated by Control Plane, or by a platform component acting on your behalf (a [Managed Kubernetes](/mk8s/overview) autoscaler reporting a failed scaling activity, for example); you do not create them directly. Most resource kinds expose a `/-eventlog` subresource that lists the events recorded against that one resource, newest first.

## Example

```bash theme={null}
cpln serviceaccount eventlog my-sa --org my-org -o json
```

```json theme={null}
{
  "kind": "list",
  "itemKind": "event",
  "items": [
    {
      "kind": "event",
      "id": "b1f6b6b0-6e3a-4b8a-8b3a-3a2b6b6b6b6b",
      "status": "serviceAccountUsed",
      "created": "2026-08-26T16:28:02.412Z",
      "lastEventTime": "2026-08-26T16:51:47.001Z",
      "eventCount": 3,
      "pinned": false,
      "context": {
        "component": "data-service",
        "fingerprint": "Xk9fQ2vR7mLpT0aZcY4bN1hW8eE1756224000",
        "keyName": "ci-key"
      }
    }
  ],
  "links": [
    { "rel": "self", "href": "/org/my-org/serviceaccount/my-sa/-eventlog" },
    { "rel": "target", "href": "/org/my-org/serviceaccount/my-sa" }
  ]
}
```

## Fields

| Field | Type | Description |
| :- | :- | :- |
| `id` | string | Unique identifier for the event log entry. |
| `kind` | string | Always `event`. |
| `status` | string | Free-form status message, up to 400 characters. |
| `created` | date | When the event was first recorded. |
| `lastEventTime` | date | When the most recent duplicate of this event was folded in. `null` until a duplicate occurs. |
| `eventCount` | number | How many times this event has recurred within the deduplication window. Starts at `1` and increments on each duplicate. |
| `pinned` | boolean | When `true`, this event is exempt from deduplication; see [Deduplication](#deduplication). |
| `context` | object | Free-form details about the event. See [Context](#context). |

### Context

| Field | Type | Description |
| :- | :- | :- |
| `category` | string | Free-form grouping for the event, such as `Deploy`. |
| `component` | string | The Control Plane component that recorded the event: `actuator`, `dns-updater`, `scheduler`, `iam-broker`, `metadata-proxy`, `data-service`, `mk8s`, or `other`. |
| `cloudProvider` | string | The cloud provider the event relates to, when applicable. |
| `cluster` | string | The location the event originated in, or absent for a globally scoped event. |
| `principalLink` | string | Reference to the principal that caused the event, when applicable. |
| `fingerprint` | string | Deduplication key chosen by the recording component, up to 64 characters. See [Deduplication](#deduplication). |

`context` also accepts additional fields specific to the component that recorded the event.

## Deduplication

An event with a `context.fingerprint` is deduplicated against events already recorded for the same resource: at most one entry per fingerprint is recorded within a 24-hour window. A repeat within that window does not create a new entry; instead it increments the existing entry's `eventCount` and updates its `lastEventTime`.

The recording component chooses the fingerprint, and many components include a time bucket in it (for example, one hour), so a recurring condition can produce a new entry more often than once a day.

Setting `pinned: true` exempts an event from this deduplication, so every occurrence is recorded as its own entry.

Events with no `fingerprint` are never deduplicated.

## Permissions

Viewing a resource's event log requires `view` on that resource. There is no separate eventlog permission, and event log entries are not something you create directly — see the [permission model](/reference/policy#permission-model) for the permissions on the resource itself.

## Supported Resources

The following kinds expose `/-eventlog`: [agent](/reference/agent), [audit context](/reference/auditctx), [cloud account](/reference/cloudaccount), [domain](/reference/domain), [group](/reference/group), [GVC](/reference/gvc), [identity](/reference/identity), [IP set](/reference/ipset), [Managed Kubernetes cluster](/mk8s/overview), [org](/reference/org), [policy](/reference/policy), [secret](/reference/secret), [service account](/reference/serviceaccount), [user](/reference/user), [volume set](/reference/volumeset), and [workload](/reference/workload/general).

## CLI

```bash theme={null}
cpln workload eventlog my-app --gvc my-gvc --org my-org
```

This is unrelated to tailing container output, which is the separate [`cpln logs`](/core/logs) command with LogQL syntax. `--max` (default `50`) caps how many entries are returned; a value less than `1` returns all entries. `eventlog` is documented on the CLI reference page for each supporting kind: [agent](/cli-reference/commands/agent#agent-eventlog), [audit context](/cli-reference/commands/auditctx#auditctx-eventlog), [cloud account](/cli-reference/commands/cloudaccount#cloudaccount-eventlog), [domain](/cli-reference/commands/domain#domain-eventlog), [group](/cli-reference/commands/group#group-eventlog), [GVC](/cli-reference/commands/gvc#gvc-eventlog), [identity](/cli-reference/commands/identity#identity-eventlog), [IP set](/cli-reference/commands/ipset#ipset-eventlog), [mk8s cluster](/cli-reference/commands/mk8s#mk8s-eventlog), [org](/cli-reference/commands/org#org-eventlog), [policy](/cli-reference/commands/policy#policy-eventlog), [secret](/cli-reference/commands/secret#secret-eventlog), [service account](/cli-reference/commands/serviceaccount#serviceaccount-eventlog), [user](/cli-reference/commands/user#user-eventlog), [volume set](/cli-reference/commands/volumeset#volumeset-eventlog), and [workload](/cli-reference/commands/workload#workload-eventlog).

## API

| Operation | Path |
| :- | :- |
| Event log for an org-scoped resource | `GET /org/my-org/agent/my-agent/-eventlog` |
| Event log for a GVC-scoped resource | `GET /org/my-org/gvc/my-gvc/workload/my-app/-eventlog` |
| Event log for the org itself | `GET /org/my-org/-eventlog` |

The response is a standard paginated list, sorted newest first, with a `target` link back to the resource the events belong to.