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

# Events

> Events are tracked user actions synced from the Event Catalog into the Semantic Catalog, with their parameters, so the agent can answer questions about behavior.

An **event** is a tracked user action — `signup_completed`, `purchase_made`, `level_finished` — brought into the Semantic Catalog so the agent can use it to answer questions. Each event comes with its **parameters**, the properties recorded with it, which you can filter and group by.

## Raw Events and Events

ClarityQ keeps two related things, and the difference matters:

* **Raw events** live in the [Event Catalog](https://docs.clarityq.ai/context-layer/event-catalog/what-is-the-event-catalog.md). They're your tracking exactly as it arrives — every event your product sends, with its parameters and user properties, quirks and all.
* **Events** live in the Semantic Catalog. They're the modeled, clean version the agent actually queries: implementation errors corrected, noise stripped out, and descriptions and rules that explain what the event means and how to use it.

The agent doesn't query the Event Catalog directly. It works from the Semantic Catalog, so an event only becomes usable once its raw event has been synced.

## What an Event Contains

Each event has:

* **Name** — Derived from the raw event's name
* **Description** — What the event means and when it fires
* **Parameters** — The event's properties and user properties, each usable for filtering and grouping
* **Rules** — Optional instructions the agent must follow whenever it uses this event (see [Rules](https://docs.clarityq.ai/context-layer/rules.md))

## How Events Are Created

Events aren't built in the Context Builder. They come from the Event Catalog:

1. Find the raw event in the Event Catalog.
2. Select it and choose **Sync to context layer**.
3. ClarityQ creates the event and its parameters **on your branch**. They go live for everyone when you deploy.

A raw event whose description is still pending becomes a **Pending** event, which the agent can already use — you approve it later. See [Syncing Events to the Semantic Catalog](https://docs.clarityq.ai/context-layer/event-catalog/syncing-events-to-the-semantic-catalog.md) for the details.

## Changing an Event

Once an event exists, you change it in the [Context Builder](https://docs.clarityq.ai/context-layer/building/how-the-context-layer-builder-works.md), like any other component. Two skills cover it:

* **`/event`** — Change an event and its parameters: descriptions (one at a time or in batch), rules, and deletions.
* **`/parameter`** — Build and fix parameters. Add a **custom parameter** when a value is worked out from the event's own row — a `CASE` or `IF` over its columns, for example.

You don't edit an event's SQL. How the event is fetched is ClarityQ's job; how to *use* it is yours, and that's what rules are for.

> [!NOTE]
>
> A value that has to be looked up in another table isn't a parameter. Keep the key the event already carries — a user ID, say — and add a **rule** to it saying which table to look the value up in.

Changes to events are versioned like the rest of the Context Layer: they're made on your branch and go live when you deploy. See [Context Layer Versioning](https://docs.clarityq.ai/context-layer/building/context-layer-versioning.md).

## How the Agent Uses Events

When someone asks about behavior — *"how many users completed signup last week?"* or *"what are the top events by volume?"* — the agent finds the relevant event and uses it to build the query. Its parameters allow breakdowns like *"signups by platform"* or *"purchases filtered to premium plan"*.

## Rules on Events

An event can carry [Rules](https://docs.clarityq.ai/context-layer/rules.md) — named instructions the agent must follow whenever it uses that event. So can **each of its parameters**: a rule on the event applies whenever the event is used, while a rule on a parameter applies to that property.

For example, on a `purchase_made` event:

**Exclude sandbox purchases** — *"Test-store transactions are present in the data before March 2026. Filter them out for any date range reaching back that far."*

And on that event's `price` parameter:

**Price is in cents** — *"Values are stored in cents. Divide by 100 before presenting an amount."*

Add and change these rules in the Builder with `/event` or `/parameter`.

## Staying in Step with the Event Catalog

An event and its raw event stay linked. New parameters join the event as you approve them in the Event Catalog, and changing a description on either side updates the other, so they always match.

Deleting an event is a change on your branch. When you deploy it, ClarityQ asks whether to also hide the matching raw event in the Event Catalog. To bring a deleted event back, sync its raw event again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.