Track Event

Record one tracked event for an identified user from your backend with POST /v2/admin/track-event.

Record a single event for a user who already exists in the project. The event is written through the same pipeline as SDK track-event (Kafka and the consumer), without updating MAU or last_seen_at.

The user must have been created with Identify User first. Authenticate with an admin API key. Admin API rate limits apply separately from SDK limits.

POSThttps://api.encatch.com/engage-product/encatch/api/v2/admin/track-event

Authentication

X-Api-KeystringRequired

Admin (secret) API key

Content-TypestringRequired

Request body format

application/json

Publishable SDK keys receive 403 (publishable API keys cannot call /v2/admin routes).

Server-side only

Keep admin API keys on your server. Never ship them in client code.

Request body

Maximum body size: 100 KB (413 if larger).

userNamestringRequired

External user id of an identified user (same value as with identify-user). Max 255 characters.

eventNamestringRequired

Event name, 1–100 characters, must contain at least one letter or digit. A new name is registered in the project even when client-created events are turned off. System events (form:*) cannot be sent through this API.

occurredAtstring

When the event happened, ISO 8601 with a time zone (e.g. 2026-09-29T10:00:00Z). Defaults to now. Must not be more than 5 minutes in the future or more than 365 days in the past.

Event policy

New events: Admin track-event registers unknown event names even when the project has client-created events turned off.
Disabled events: Events marked disabled in the project are rejected.
Triggers: Events older than 15 minutes update counts and segments but do not evaluate form triggers. Matched forms are queued for the user's next visit, not shown immediately.
Metering: On production API key environment (P), metered event tracking limits apply (402 when exhausted). Registering a new event name also checks the unique tracked-events limit in P only.

Examples

cURL

curl -X POST 'https://api.encatch.com/engage-product/encatch/api/v2/admin/track-event' \
  -H 'X-Api-Key: YOUR_ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "userName": "alice@example.com",
    "eventName": "Plan Renewed",
    "occurredAt": "2026-09-29T10:00:00Z"
  }'

Success response

202Response

{
  "requestId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "occurredAt": "2026-09-29T10:00:00Z",
  "newEvent": true,
  "triggersEvaluated": true,
  "formsQueued": 1,
  "message": "Event recorded. 1 form(s) will show on the user's next visit."
}

requestIdstringRequired

Correlation id for this call.

occurredAtstringRequired

UTC time the event was recorded with.

newEventbooleanRequired

True when the event name was new and is now created in the project.

triggersEvaluatedbooleanRequired

False when the event is older than 15 minutes (counts and segments only).

formsQueuednumberRequired

Number of forms matched and queued for the user's next visit.

messagestringRequired

Human-readable summary of trigger and form behavior.

Errors

These are specific to Track Event. Shared errors include invalid or missing API key (401), publishable key on admin routes (403), rate limits (429), and sanitized 500 responses.

404Error

{
  "status": 404,
  "error": "Not Found",
  "message": "User not found"
}

Status	When
`400`	Missing or invalid `userName`, `eventName`, or `occurredAt`; system events (`form:*`); disabled event; empty slug; unique tracked-events limit (`Unique tracked events limit reached for your plan`)
`402`	Event tracking limit reached in production (`Event tracking limit reached for this organization`)
`404`	User not found (`User not found`)
`413`	Request body larger than 100 KB

Identify User: create the user before tracking events