---
title: Event catalog
description: See every event your project has produced, its display name, status, and downstream consumers — without querying raw event rows.
---

Retidal automatically discovers every distinct `eventName` your project sends and keeps
a per-event record: its display name, lifecycle status, category, and what downstream
features (mappings, automations, derived rules) consume it. This is the catalog view —
distinct from the raw event log, which lists individual event rows rather than event
*definitions*.

## Prerequisites

- Events already flowing through [Sending events](/docs/sending-data/events) — an event
  name only appears in the catalog once at least one event carrying it has been ingested.

## Authentication

Every endpoint on this page is a **Management API** call — host `https://retidal.com`,
authenticated with the `trackly_session` cookie from a logged-in console user, not a
project API key. See [Authentication](/docs/authentication) for the full model.

## Global event definitions

```
GET https://retidal.com/api/event-definitions
```

Lists the global, cross-project standard event definitions (any authenticated dashboard
user can read this list) — the reference set your project events can be mapped onto via
[Event mappings](/docs/sending-data/event-mappings).

<Note>
  This is separate from the `SUPER_ADMIN`-only `GET /api/admin/events`, which lists
  event definitions with usage stats and is not available to project users.
</Note>

## Your project's event catalog

```
GET https://retidal.com/api/projects/{projectId}/project-events
```

Paginated, searchable list of every event name this project has produced, each with its
current lifecycle `status` (`DISCOVERED` / `ACTIVE` / `DEPRECATED` / `PLANNED` /
`BLOCKED`), category, and mapping state. Supports `page`, `limit`, `search`, `status`,
and `category` query parameters.

<ParamField name="status" in="query" type="string">
  Filter to one lifecycle status: `DISCOVERED`, `ACTIVE`, `DEPRECATED`, `PLANNED`, or
  `BLOCKED`.
</ParamField>

Console → Projects → Project Events shows this same catalog, with inline display-name
editing and per-event volume and consumer detail.

### Volume trend (optional)

```
GET https://retidal.com/api/projects/{projectId}/project-events/trends
```

A 7-day per-event volume sparkline, derived from Analytics Engine and KV-cached — returns
an empty map (not an error) when Analytics Engine is temporarily unavailable, so a blank
sparkline is not itself proof an event stopped arriving.

### Renaming a catalog entry (optional)

```
PATCH https://retidal.com/api/projects/{projectId}/project-events/{eventName}
```

Updates only the event's display name shown in the console — it does not change the
`eventName` your integration sends, and does not affect mapping or downstream consumers.

## Downstream consumers

```
GET https://retidal.com/api/projects/{projectId}/project-events/{eventName}/consumers
```

Read-only topology graph (`{ nodes, edges }`) showing which triggers, automations, and
derived rules subscribe to a given event name — this is how you confirm an event is
actually wired to something downstream, not just arriving.

## Sampled property keys (optional)

```
GET https://retidal.com/api/projects/{projectId}/event-property-keys
```

A sampled (7-day window, 10-minute KV cache) list of property keys seen on this
project's events, with a sample value and occurrence count each — useful as an
autocomplete source when configuring a mapping or derived rule condition, not a
guaranteed-complete schema.

## The raw event log is a different page

Console → Projects → Events is the raw event log — individual event rows with
pagination, a date range, and property filters. It is a good place to confirm a specific
event landed, but it is not the event catalog: it has no lifecycle status, no display
name, and no consumer topology. Use the catalog above for "what events exist and what
depends on them"; use the raw log to inspect one event's actual payload.

## What this unlocks

The catalog is what makes [Event mappings](/docs/sending-data/event-mappings) and
[Derived rules](/docs/sending-data/derived-rules) safe to configure against real event
names instead of guessing — and the consumers endpoint tells you what breaks downstream
before you rename or deprecate an event.

## Verify it worked

```
GET /api/projects/{projectId}/project-events?limit=5
```

`GET /api/projects/{projectId}/project-events` returns `200` with `{ events, categories,
pagination }` — confirm a recently-sent test event name appears in `events[]` within a
few minutes, or check the same thing at Console → Projects → Project Events.

## If it doesn't work

If an event you sent never appears in the catalog, or its volume/consumers view reads as
zero or stale, work through
[Events not arriving](/docs/troubleshooting/events-not-arriving) — the root cause is the
same as an event never being received in the first place.