---
title: "Track event"
method: POST
path: "/v1/track"
tags: ["Public API"]
---

# Track event

`POST /v1/track`

Track an event for a contact. Automatically creates or upserts the contact, then records the event. Tracked events can be used as workflow triggers, segment filters, and audience filters.

**Reserved event names** (rejected with `VALIDATION_ERROR` and code `reserved_event`): anything matching `email.*`, `contact.subscribed`, `contact.unsubscribed`, `segment.<slug>.entry`, `segment.<slug>.exit`. These are emitted by Plunk itself.

**Idempotency**: re-tracking the same event creates a new event record. Send an `Idempotency-Key` header to have a repeated request refused with `409` instead.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `email` string, email, required — Contact email. The contact is auto-created if it doesn't exist.
  - `event` string, required — Event name. Cannot match the reserved patterns above.
  - `subscribed` boolean — Subscription state to apply to the contact. **New** contacts default to subscribed (`true`). **Existing** contacts keep their current state unless you pass an explicit value here. Pass `false` to track an event without resubscribing an unsubscribed contact.
  - `data` object — Contact data and one-off event variables. Persistent values (primitives, plain objects) are saved on the contact and become available as template variables. Pass `{ value, persistent: false }` for one-shot variables that should not be stored on the contact (e.g. order IDs, transaction details). `null` deletes a field. Empty strings are ignored. Reserved keys are filtered out — see the contacts concept page.

## Response `200`

Event tracked successfully

- object
  - `success` boolean
  - `data` object
    - `contact` string — Contact ID
    - `event` string — Event ID
    - `timestamp` string, date-time

## Other responses

- `401` — Missing or invalid API key.
- `409` — Idempotency-Key already used. The request was refused, not performed.
- `422` — Request body failed schema validation. `error.errors` lists the offending fields.

---

[API](https://skmtc.dev/useplunk/apis/plunk-api.md) · [All operations](https://skmtc.dev/useplunk/apis/plunk-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/useplunk/plunk-api/revisions/a13aa5345f8e/schema)