> Source: https://builder.ema.ai/v2/builder-guides/custom-events
> Title: Tracking Custom Events

# Tracking Custom Events

A **custom event** records something your AI Employee does that the built-in metrics don't capture, such as an invoice approved, a claim paid, or a ticket closed. Each time a published run reaches the step that records it, Ema saves one **entry** with the values you chose. You then chart those entries on the **Metrics** tab, the same way you chart workflow runs or tool calls.

> [INFO]
> **Custom events are enabled per Workspace.** If you don't see an **Events** button on an AI Employee's Metrics tab, custom events are not turned on for your Workspace. Ask your Ema contact.

## How it works

1.  **Define the event.** Give it a name, a description of when it's recorded, and the fields to save with each entry.
2.  **Record it in the workflow.** Add an [Emit Event Agent](/builder/v2/agent-reference/emit-event) and connect each field to a value from an earlier step.
3.  **Publish the AI Employee.** Published runs record entries. Test runs in the editor do not.
4.  **Chart it.** Add a chart on the Metrics tab and pick the event as its dataset.

## Where to find events

Events live in three places, one for each scope an event can belong to.

Scope

Where

What you see

AI Employee

Open the AI Employee, select the **Metrics** tab, then **Events**.

The events this AI Employee records, both its own and the shared events it uses.

Group

Open the Group, select the **Metrics** tab, then **Events**.

Events shared with the Group. AI Employees in the Group can use them, and their entries add up in the Group's Metrics.

Workspace

Select **Metrics** in the main navigation, then the **Events** tab.

Events defined across the Workspace, its Groups, and its AI Employees.

The Events panel on an AI Employee has two tabs, **Events** and **Calculated fields**. This page covers **Events**.

## Create an event

Open the AI Employee's Events panel and select **New event**. Choose how to start:

-   **Describe with Autopilot.** Autopilot asks whether you want to use an event your Group or Workspace already shares, or build a new one. For a new event it asks what outcome you want to record, proposes the fields, and proposes the step that records it with its fields connected. It shows you the plan before it changes anything, and it does not publish without your approval.
-   **Add manually.** Choose **Use a shared event** to join an event your Group or Workspace already has (see [Use a shared event](#use-a-shared-event)), or **Build your own** to define a new one.

### Build your own

1.  Enter an **Event name**, for example "Invoice processed". Names can be up to 100 characters.
2.  Enter a **Description** that says when the event is recorded, for example "When a support ticket is closed."
3.  Add **Fields**:
    -   Select **Pick fields from AI Employee outputs** to choose outputs that steps in this workflow already produce. The field's type comes from the output.
    -   Select **Add field** for a value no step produces yet. You choose or create its source later, when you connect the Emit Event Agent.
4.  Select **Save and add to workflow**.

The event is saved to the AI Employee's draft. Next, connect its fields in an Emit Event Agent, then publish the AI Employee. See [Record the event in the workflow](#record-the-event-in-the-workflow).

> [TIP]
> **Use IDs, not names or email addresses.** Every entry is stored and can be charted and exported. Record an invoice ID or a ticket ID rather than a person's name or email address.

### Fields

Each field has a name, a type, an optional description, and a **Required** setting. Field names must be unique within the event.

Type

Values

Limit per event

String

Text.

15

Number

A finite number.

15

Boolean

True or false.

10

Date

A calendar date, written `YYYY-MM-DD`.

10, for dates and datetimes combined

Datetime

A date and time with a timezone, in RFC 3339 format, for example `2026-11-09T14:30:00Z`.

An event can have up to 50 fields in total. Each field holds a single value: lists and nested objects are not supported.

-   **Required.** Fields are optional by default. If a required field has no value when the step runs, that entry is not recorded.
-   **Default for earlier events.** Under **Advanced · Earlier events**, you can give a field a default value. Charts use it for entries recorded before the field existed, so adding a field doesn't leave older entries blank.

## Record the event in the workflow

Defining an event doesn't record anything on its own. A step in the workflow has to record it.

### With an Emit Event Agent

The [Emit Event Agent](/builder/v2/agent-reference/emit-event) records one entry each time it runs. Find it in the **Planning & Resources** group of the agent library.

1.  Open the workflow in the AI Employee builder and add an **Emit Event Agent** after the step whose outputs hold the values you want to record.
2.  Under **Event**, select the event. Only events in this AI Employee's Events panel appear here.
3.  For each field, connect an output from an earlier step, or choose **Constant** and enter a fixed value. Optional fields you leave unbound are left out of the entry.
4.  Save the workflow, then publish the AI Employee.

You don't need fields for which Workspace, AI Employee, or run an entry came from. Ema adds those to every entry automatically.

If you change an event's fields after adding the step, the step shows that the fields changed. Select **Reload event schema**. Connections to fields that still exist with the same type are kept. Connections to removed or changed fields are cleared, and you need to connect any new required field before you publish.

### From a Code Agent script

A [Code Agent](/builder/v2/agent-reference/code-agent) script can also record an event with the built-in `emit_event` function. It takes exactly two arguments: the event's **alias** and an object of field values.

```typescript
function main(inputs: Inputs) {
  for (const invoice of inputs.invoices) {
    if (invoice.status === "approved") {
      emit_event("Invoice processed", {
        invoice_id: invoice.id,
        amount: invoice.amount,
        status: invoice.status,
      });
    }
  }
  return { recorded: inputs.invoices.length };
}
```

The alias is shown in the event's details on the AI Employee's Events panel. Use it exactly as shown. It stays the same if the event is renamed. Field names that contain spaces must be quoted in your script.

If Ema rejects an entry, for example because a required field is missing or a value has the wrong type, `emit_event` throws an error. Catch it to keep the script running, or let it fail the step.

Use a script when one run should record several entries, or when the values need logic to work out. Otherwise, the Emit Event Agent is simpler and Ema can check that it's connected.

## Publish and check that it's recording

Events are recorded only by published runs. Test runs in the editor and evaluation runs don't record entries: the Emit Event Agent shows the entry it would have recorded instead.

The **Status** and **Next step** columns on the AI Employee's Events panel tell you where each event stands.

Status

What it means

Next step

Draft

The event was saved but not published.

Open it and select **Save and add to workflow** again.

Not in workflow

No Emit Event Agent records this event yet.

Add an Emit Event Agent and connect its fields.

Not published

An Emit Event Agent records it in the draft, but the draft isn't published.

Publish the AI Employee.

Recording

Published runs record this event.

Chart it. If a chart is empty, check for recent runs and the chart's date range.

Couldn't check

A Code Agent script may record it. Ema can't look inside scripts.

Look for the event in a recent published run.

## Chart an event

1.  On the **Metrics** tab, select **Edit dashboard**, then **Add** and **Chart**.
2.  Open the dataset list. Your events appear under **Your events**, with their version.
3.  Pick a chart type and measures, for example a count of entries, and group or filter by the event's fields.
4.  Save the chart, then publish the dashboard.

Everything in [Building a custom metrics view](/builder/v2/builder-guides/custom-metrics-views) applies to event charts: chart types, filters, drafts, and publishing. On a Group's Metrics tab, a shared event's entries add up across every AI Employee in the Group that records it.

## Share events across AI Employees

Sharing lets several AI Employees record the same event, so their numbers add up in Group and Workspace charts.

### Share an AI Employee's event with its Group

Open the event on the AI Employee's Events panel and select **Share with** your Group. Other AI Employees in the Group can then use it. This AI Employee keeps recording it and its history stays. You can't undo a share.

After sharing, the Group's event managers decide future changes to its fields. Edits you haven't published are not shared. If the AI Employee leaves the Group, it can no longer record the event.

To share, you need edit access to the AI Employee and permission to manage the Group's events. The AI Employee must belong to a Group.

### Use a shared event

1.  On the AI Employee's Events panel, select **New event**, then **Add manually** and **Use a shared event**.
2.  Pick an event. The **Matches your outputs** column shows whether this AI Employee produces every field the event needs. A match is by field name and type.
3.  Connect its fields in an Emit Event Agent, then publish.

You can only pick an event when this AI Employee produces all of its fields. A shared event stays up to date when its Group or Workspace changes it.

### Create and promote shared events

On a Group's Events panel, select **New Group event** to define fields every AI Employee in the Group should record. Each AI Employee connects its own values.

You can also promote an existing event to a wider scope: an AI Employee's event from the Group's Events panel, or any Group or AI Employee event from the Workspace **Events** tab. Promoting makes a shared copy with the same fields. AI Employees that already use the original stay as they are.

### See which AI Employees use an event

The **Used by** column on the Group and Workspace events lists counts the AI Employees that use each event. Select it to see them, with whether each one uses the event in its current draft or its published version. The list shows only AI Employees you have access to.

## Change or stop recording an event

-   **Edit an event.** On an AI Employee, your changes are saved to its draft and take effect when you publish it. Published changes reach every AI Employee that uses the event, and charts keep their history. If a change removes or renames fields, Ema asks you to confirm in **Review breaking changes**, because removed fields can break workflows and charts that use them.
-   **Edit a shared event.** A shared event's fields are managed where it's shared from, so you can view it on an AI Employee but not edit it there. On the Group or Workspace Events panel, saving publishes the change to every AI Employee that uses it.
-   **Stop recording.** On an event that belongs to the AI Employee, select **Stop recording**. It stops after you publish. Remove its Emit Event Agent from the workflow too, or publishing fails. Past entries and charts stay.
-   **Remove a shared event from an AI Employee.** Select **Remove from AI Employee**. Entries it already recorded stay available in Metrics.

## Export and import events

Group and Workspace Events panels can copy event definitions between Groups or Workspaces.

-   **Export.** Select one or more published events, then **Export selected**. Ema saves their definitions to a JSON file. Charts and recorded entries are not included.
-   **Import.** Select **Import events** and choose a file made with **Export selected**, smaller than 1 MB. Review the destination, then confirm. The events are added with their fields. Existing events are not overwritten.

To move an AI Employee together with its events and charts, use the AI Employee's own export instead. See [AI Employee export and import](/builder/v2/administration/ai-employee-export-import).

## Who can manage events

-   **On an AI Employee:** anyone who can edit the AI Employee.
-   **On a Group or the Workspace:** people who can edit metrics. Seeing events from AI Employees across the Workspace also needs Workspace-wide Metrics access.

## Troubleshooting

Symptom

Cause and fix

No **Events** button on the Metrics tab.

Custom events are not turned on for your Workspace. Ask your Ema contact.

The status is **Recording** but the chart is empty.

No published run has reached the Emit Event Agent in the chart's date range. Test runs don't record entries. Run the published AI Employee, then check the dashboard's date range.

Some runs didn't record an entry.

A required field had no value in those runs. Check the step that feeds it, or make the field optional.

The event doesn't appear in the Emit Event Agent's **Event** list.

Only events in this AI Employee's Events panel appear. Add or join the event there first.

Publishing fails after you changed an event's fields.

The Emit Event Agent still uses the old fields. Open it, select **Reload event schema**, connect any required fields, save, and publish again.

Publishing fails after you selected **Stop recording**.

The workflow still has an Emit Event Agent for that event. Remove it, then publish.

A shared event shows **Doesn't match**.

This AI Employee doesn't produce every field the event needs. The hint lists the missing fields. Add those outputs to a step, then try again.

Import says "This JSON is not an event export."

The file wasn't made with **Export selected**. Export the events again from the source Group or Workspace.

## What's next

-   [Emit Event Agent](/builder/v2/agent-reference/emit-event): the agent's configuration and output in detail.
-   [Building a custom metrics view](/builder/v2/builder-guides/custom-metrics-views): build and publish charts on an AI Employee's Metrics tab.
-   [Building a Workspace metrics view](/builder/v2/builder-guides/custom-metrics-workspace): chart events across the whole Workspace.
-   [Code Agent](/builder/v2/agent-reference/code-agent): write the scripts that can call `emit_event`.
