# Events

Source: https://kirora.io/docs/guides/contacts/events

See the events your workspace receives, check each one as it arrives, and use events in segments, journeys and goals.

An event is a record of something a contact did, such as *Order Completed*, *trial.started* or *appointment.booked*, with details such as the amount in its properties. Events let journeys react to what people do, let segments find people by their behaviour, and let goals measure results.

You'll find them on the **Data index** page, under **Configure** in the sidebar. It has three tabs: **Events**, **Event log** and **Attributes**. For **Attributes**, see [Contact attributes](https://kirora.io/docs/guides/contacts/attributes#see-every-attribute-in-your-workspace).

## How events arrive

Events come from your own systems, never from typing them into the dashboard:

- **Your server**, through the API. See [Events](https://kirora.io/docs/api/events).
- **The web SDK** on your website, which can also record visits and page views. See [Web SDK](https://kirora.io/docs/sdks/web).
- **A connected integration**: Stripe, Zapier, Make, n8n or Segment. A payment provider sends orders as *Order Completed*. See [Connect an integration](https://kirora.io/docs/guides/integrations/connect-an-integration).
- **Kirora itself**, for things that happen inside Kirora, such as a contact joining a list.

Each event belongs to a contact who already exists, found by their Kirora ID, your external ID or their email address. Create or update the contact first, then send their events.

You can send your own events through the API or the SDKs on every plan, up to your plan's tracked events a month; see [Plans and billing](https://kirora.io/docs/guides/account/plans-and-billing#what-counts). Kirora's own events don't count.

## The events your workspace knows

The **Events** tab lists every event name your workspace has, with its **Source**:

| Source | What it means |
| --- | --- |
| **Your app** | A name your app, website or an integration has sent, or one added before it's sent |
| **Standard** | One of Kirora's standard names, such as *Order Completed*, *Checkout Started* or *Trial Started*, that your workspace has sent or added. Use the [standard names](https://kirora.io/docs/api/events#defining-a-name-before-you-send-it) when they fit, so you don't need names of your own |
| **Kirora** | An event Kirora records itself, such as `contact.added_to_list`, `contact.form_submitted` or *Ordered Product* |

Each name shows its description beneath it, and its figures:

- **Last 30 days**: how many of its events arrived in the last 30 days.
- **Last seen**: when its latest event happened, or *Not received yet* when it has none.
- **Used by**: how many journeys, segments, campaigns and goals read it.

The figures can be up to 15 minutes old, but a name sent for the first time shows at once. Names with events come first, the most recent first. Choose **Event**, **Last 30 days** or **Last seen** to sort by that column, search by name, or filter by **Source**.

Standard names you haven't sent aren't listed here. Event fields in segments, journeys, goals and Kiro AI tasks suggest them after your own names.

Choose a name to open its page:

- **Activity**: how many arrived in the **Last 30 days**, and when the last one was **Last received**.
- **Used by**: the journeys, segments, campaign audiences, conversion goals and workspace goals that read it. Check this before you rename an event in your app.
- **Properties**: the keys its recent events carried, with their **Type**, a few **Examples** and how often each was **Seen in** them. Examples of a hidden attribute show as **Hidden** to members, authors, developers and viewers.
- **Recent events**: the last 20, with when each happened, the contact, what sent it and its properties. Use this to check an integration sends what you expect.

### Add an event before it's sent

Admins and the owner can add an event name before your app sends it, so a journey, segment or goal can be built on it while your developers add the tracking.

1. On the **Events** tab, choose **New event**.
2. Enter the **Name** exactly as your app will send it, and optionally a **Description** of what it means.
3. Choose **Create event**.

The name shows *Not received yet* until its first event arrives. A name that's already listed can't be added again; open it to edit its description instead. Your developers can also add a name through the API. See [Defining a name before you send it](https://kirora.io/docs/api/events#defining-a-name-before-you-send-it).

### Describe an event

A description says what an event means, in your workspace's words, such as *A customer booked a table online*. It shows under the name on the **Events** tab and on the event's page, and Kiro AI reads it as the event's meaning. Kirora's own events and the standard names come with a description already.

Admins and the owner can describe any name except Kirora's own. Open the name, choose **Edit**, write the **Description** (up to 255 characters), then choose **Save changes**. Clear it to remove it.

### Event names

A workspace can track up to 1,000 event names, including names added before they're sent; Kirora's own don't count. When you're close, the **Events** tab warns you, and past the limit new names are refused. Keep names for what happened, such as `trial.started`, and put IDs, amounts and other changing values in the event's properties, not the name.

Names are case-sensitive, up to 128 characters. Names starting with `contact.` are reserved for Kirora, and *Ordered Product* is recorded by Kirora from each line of an *Order Completed*, so you can't send either yourself.

### Delete an event name

Admins and the owner can delete a name your app sent or someone added, for example one sent by mistake. Open it, choose the more actions button (⋯), then **Delete**, then **Delete event**. The name and all its events are removed within the hour, and it can't be tracked again for up to an hour.

You can't delete a name while anything uses it. The page lists what does; change or delete those first. Kirora's own events can't be deleted.

## Check events as they arrive

The **Event log** tab shows every event tracked in the last 30 days, newest first, including the ones Kirora refused. Use it to check an integration without looking up a contact first.

Each row shows the **Event**, the **Contact**, its **Status** (**Accepted** or **Rejected**), what it was **Sent by** (such as **Your server**, **Web SDK**, **Kirora** or **Stripe**) and **When** it happened. An event sent more than a minute after it happened also shows when it was received.

- Search by event name or contact email, and filter by **Status** or **When** (**Last hour**, **Last 24 hours** or **Last 7 days**).
- Choose **Details** to see what was stored, or, for a rejected event, why it was refused and what was sent. A refused event over 32 KB isn't kept.
- The log doesn't update by itself. Reload the page to see new events.

A rejected event shows when it arrived, and searching by contact finds accepted events only, because a refused event never reached a contact.

### Why an event is rejected

The **Status** column gives the reason. Common ones:

| Message | What to do |
| --- | --- |
| *No contact matches `email`* (or `externalId`, `contactId`) | Create or update the contact first, then send the event |
| *An event time may be at most 24 hours in the future* | Check the event's time and your server's clock |
| *properties must be at most 16384 bytes* | Send less in the event's properties |
| *This workspace tracks 1000 event names, the most it can…* | Delete names you don't use, and move changing values into properties |
| *This event name was deleted and its events are still being removed; track it again in an hour* | Wait an hour, then send it again |
| `contact.* event names are reserved for the platform` | Use your own name for the event |

The full list of errors is in [Events](https://kirora.io/docs/api/events) and [Errors](https://kirora.io/docs/api/reference/errors).

## A contact's events

A contact's events are on their profile's **Timeline**. Choose **Show**, then **Events**, to see only those. See [A contact's profile](https://kirora.io/docs/guides/contacts/contact-profile#timeline).

Events are kept for 30 days on Free and a year on paid plans, from when each event happened. See [Data retention](https://kirora.io/docs/guides/account/data-retention#your-plans-history-period).

## Use events

- **In segments.** The **An event** condition finds people by what they did, how often and how recently, with optional property filters, such as *Order Completed at least once within 30 days*. See [Segments](https://kirora.io/docs/guides/contacts/segments#kinds-of-conditions).
- **To start journeys.** The **An event happens** trigger starts a journey when a matching event arrives, optionally only for events with certain properties. Journeys can also wait for an event or end when one arrives. See [How journeys work](https://kirora.io/docs/guides/journeys/how-journeys-work#triggers-how-contacts-enter).
- **To measure results.** A campaign or journey's conversion goal counts an event, such as a purchase, after a message. Workspace Goals measure events across the business. See [How goals work](https://kirora.io/docs/guides/goals/how-goals-work).
- **As key events.** Tell Kirora which events mean a transaction, a sign-up or a cancellation, so customer groups, value totals and ready-made goals can read them. See [Set your key events](https://kirora.io/docs/guides/goals/key-events).

## Frequently asked questions

### Why doesn't my event appear?

Open the **Event log** and filter by **Rejected**. A refused event shows the reason. If it isn't there at all, it never reached Kirora: check the API key and the address your app sends to.

### Can I add an event by hand?

No. Events come from your app, your website, an integration or Kirora itself. You can [add an event's name](#add-an-event-before-its-sent) before it's sent, but not the events themselves. To mark something about a contact by hand, set an attribute or add them to a list instead.

### Why didn't an old order start my journey?

An event that arrives more than 72 hours after it happened doesn't start a journey, so an old order doesn't trigger a message. It still counts in segments, goals and customer groups.

## Next steps

- [Events](https://kirora.io/docs/api/events) — send events from your server
- [Segments](https://kirora.io/docs/guides/contacts/segments) — find people by what they did
- [How journeys work](https://kirora.io/docs/guides/journeys/how-journeys-work) — start a journey when an event happens