---
title: "Events and the event registry"
description: "How Togo turns the event names your code sends into stable keys you query by, and what defining an event adds."
canonical: "https://www.togohq.ai/docs/concepts/events"
applies_to: "Every Togo SDK and the MCP server"
updated: "2026-11-03T00:00:00Z"
---

# Events and the event registry

How Togo turns the event names your code sends into stable keys you query by, and what defining an event adds.

## Traffic decides which events exist

The first time Togo processes an event name, it records it in your project's **event registry**,
and from then on that event can be queried, with every property it was sent with — so nothing your
code sends is lost while you define it. An event the code stops sending stays in the registry with the
date it was last seen.

## Raw names and keys

Your code's name for an event is its **raw name**, and Togo stores it exactly as sent — `Sign Up`
stays `Sign Up`, and is never rewritten in your data.

Each raw name is given a **key** once, derived from the name: lowercase, `snake_case`. Reports,
the AI analyst and every MCP tool name events by key.

| Raw name sent        | Key                  |
| -------------------- | -------------------- |
| `Sign Up`            | `sign_up`            |
| `checkout_completed` | `checkout_completed` |
| `Button Clicked`     | `button_clicked`     |

**A key never changes after it is derived.** If a second raw name would derive to a key that is
already taken — `sign up` after `Sign Up` — it gets a new key (`sign_up_2`) and the registry
suggests merging the two. Nothing is merged silently.

## Merging two names for one event

When one event has been sent under two names, merge the keys: the raw names counted under one
count under the other from then on, and every past answer re-counts with the merged history. No
data is rewritten. An agent can do it with
[`merge_events`](/docs/reference/mcp-tools#merge_events). **A merge cannot be undone**, so it asks
you first.

## Defining an event

**Define every event you rely on.** A definition is how the registry learns what an event
_means_: a description, when it fires, when it does **not** fire, and the properties it carries
with their types. It is what makes your numbers mean the same thing to everyone who reads them, and
what gives your agent the context to answer correctly —
[Event governance](/docs/concepts/governance) explains why it matters and how Togo enforces it.

The install flow defines your events before it writes the tracking code
([Install Togo with your AI agent](/docs/install)). An agent can define or edit one at any time
with [`update_event_definitions`](/docs/reference/mcp-tools#update_event_definitions). Once an event has traffic, a change
that would break code already sending it — a narrower type, a removed allowed value — is refused
with the reason.

Once your plan covers your traffic, turn on **strict event governance** so only defined events
reach your reports ([Event governance → Strict event governance](/docs/concepts/governance#strict-event-governance)).

## Naming new events

Keep the names you have. For new ones, use lowercase `snake_case` past-tense names, and put a
namespace in a property rather than in the name: `page_viewed` with `surface: "marketing"`, never
`marketing.page_viewed`. Names that start with `$` are reserved for Togo's own events and are
refused.

Event names and property keys are permanent once sent: they can be merged, never renamed.