Key events
A key event is an action that matters to your business: Lead captured, Qualified, Revenue realized, Activated. You decide what reaches it, once, and Attribution, campaign steps, ad platform sends and Targets all count the same thing.
Info
Four words, four jobs. A key event is what you define. A Metric is what one experiment measures. A conversion is what an ad platform calls the sale or lead Apex sends it. A Target is a number you commit to by a date.
What reaches a key event
A key event has one or more events that reach it. Any one is enough. Each event can carry conditions on its data, and every condition must hold.
| Lead captured is reached by | When |
|---|---|
application_submitted | always |
audit_booked | plan equals pro |
Someone who submits an application reaches Lead captured. Someone who books an audit on the starter plan does not.
Key events count two kinds of event:
| Kind | What it counts | Example |
|---|---|---|
A named event (custom_event) | An event your site, app or server sends | purchase, lead_qualified, trial_started |
A form submission (form_submit) | A form sent on your site. Pick one form by its #id and one page, or count any form | The demo request form on /contact |
Clicks and page views only count inside an experiment, as that experiment's own Metric. A click is too easy to fire by accident to stand for a lead or a sale.
Conditions read the event's data, with dots for nested fields (plan, order.channel):
| Condition | Holds when |
|---|---|
equals / not_equals | The field is (or is not) exactly this value. "10" and 10 are different. |
in | The field is one of a list |
exists / not_exists | The field is there (or is missing) |
People or companies
A key event counts people by default. Set it to count companies and a company reaches it when its first person does, so a team of five who all book a demo counts once. Send account_id on the event, or identify people with their account.
Changing a key event
Renaming a key event changes nothing it counted. Changing what reaches it, its conditions, or whether it counts people or companies makes a new version:
- People already counted keep the version they reached.
- A running experiment keeps the version it started with.
- Each version is kept, with who changed it and when.
People who already did it
When you make a key event or change what reaches it, Apex also looks back through each person's history and counts who already did it. Those people are marked as found in history, not seen as it happened. Apex never sends them to an ad platform, starts a journey for them, or emails them because of it.
Sending the events
Send named events from wherever the truth lives. A purchase or a CRM stage change belongs on your server:
import { sendServerEvent } from "@apex-inc/sdk";
await sendServerEvent(
{ apiKey: process.env.APEX_API_KEY! },
{ type: "lead_qualified", email: "dana@example.com", country: "US", data: { lead_id: "L-204", stage: "sql", account_id: "acme" } },
);
Pass country (a two-letter code) on server events. Your server sends from its own location, so Apex never guesses one, and a sale with no country is held back from ad platforms when you ask for consent only where the law requires it.
From the browser, use the snippet or the SDK:
window.apex?.track("application_submitted", { plan: "pro" });
The event name in your code must match the name on the key event exactly. The Apex Spec lists the standard names, including lead_qualified and lead_lost for sales teams.
Making key events
- In Apex: open Key events in the dashboard.
- From your AI agent: ask it to make one. It uses
create_key_event. See MCP tools. - From code:
apex.keyEvents.create(...)in the SDK, or the Key events API.
One key event is your main key event. Attribution leads with it.
Segments and journeys
The same key events work across your audiences and Adaptive Journeys, counted the same way Attribution counts them:
- Segments: "has reached Qualified" or "hasn't reached it", optionally within the last N days, or "anyone at their company has".
- Journey branches: send a different letter to people who reached a key event.
- Journey exits: stop a journey the moment someone reaches one, however they got there.
- Journey goals: aim a journey at a key event, so its results and the tests inside it are judged on it.
A lead nurture is the usual shape: start it when someone becomes a lead, stop it when they reach Qualified, and aim it at Qualified.
Ad platforms
A key event can be sent to Meta, Google, LinkedIn and others as their conversion. What an ad platform says it drove is always shown apart from what Apex counted, and never added to it. Every number Apex shows comes from one source, never a blend. See Attribution.
Targets
A Target is a number you commit to by a date: MRR, pipeline, 1,000 signups by Q3. Tie a Target to one key event and Apex counts its progress for you; otherwise you update it yourself. See the Targets & Conversions API.
Good habits
- Name it for the business, not the event. "Lead captured" outlives the form it counts today.
- Prefer a named event over a form when you can send one. Forms change; event names don't have to.
- Change, don't duplicate. If what counts as a lead changes, update the key event. Its version history shows when.
- Use an
#idon forms. It still matches after a redesign that moves the form.