---
title: "Track an event"
method: POST
path: "/events"
tags: ["v2.0"]
---

# Track an event

`POST /events`

This endpoint creates a new event for a user, persisting the event in Permutive for downstream consumption, such as for segmentation, insights, or routing to a data lake. It validates the event against the schema defined in your workspace, and generates an event ID for the event and optionally enriches the event with geo, ISP, and contextual data.

## Query parameters

- `enrich` boolean
- `sdkp` boolean

## Request body

- PostEvent
  - `user_id` string, uuid — The Permutive user ID of the user that the event belongs to. If you do not provide a user ID, you must provide a non-empty list of aliases in the `aliases` field.
  - `aliases` PrioritizedAlias[] — A non-empty list of prioritized aliases that the user is associated with. If you do not provide a list of aliases, you must provide a user ID in the `user_id` field. Prioritized aliases allow customers to express which identifiers they consider most reliable or authoritative for resolving user identities. When multiple aliases are provided, priorities are used to determine the order in which aliases are attempted for resolution to a Permutive user ID, where priority `0` has the highest priority.
    - `priority` integer, required — The priority of the alias, where `0` is the highest priority.
    - `tag` string, required — The tag is a string used to identify the type of alias, e.g. `email_sha256` or `myInternalID`.
    - `id` string, required — The identifier for the alias, e.g. `user@example.com` or `1234567890`.
  - `name` string, required — The name of the event collection this event belongs to. The name is case-insensitive and must only contain characters in `[a-zA-Z0-9_]`.
  - `view_id` string, uuid — The identifier for the view in which the event is taking place. This is used to group events within a single page or screen view.
  - `session_id` string, uuid — The identifier for the session in which the event is taking place. This is used to group events within a user session.
  - `segments` integer[] — The list of segment codes that the user belonged to at the time of the event.
  - `cohorts` string[] — The list of cohort IDs that the user belonged to at the time of the event.
  - `properties` object — The properties that belong to this event. These properties must adhere to the specific schema configured for this event collection.

## Response `201`

Event created successfully

- union
  - EventResponse
    - `user_id` string, uuid, required — The Permutive user ID of the user that the tracked event belongs to.
    - `name` string — The name of the event collection the tracked event belongs to. The name is case-insensitive and must only contain characters in `[a-zA-Z0-9_]`.
    - `time` string, date-time — The ISO 8601 timestamp of the event.
    - `view_id` string, uuid — The identifier for the view in which the tracked event took place.
    - `session_id` string, uuid — The identifier for the session in which the tracked event took place.
    - `segments` integer[] — The list of segment codes that the user belonged to at the time the event was tracked.
    - `cohorts` string[] — The list of cohort IDs that the user belonged to at the time the event was tracked.
    - `properties` object — The properties that belong to the tracked event. These properties adhere to the specific schema configured for this event collection.
  - EventUnenrichedResponse
    - `user_id` string, uuid, required — The Permutive user ID of the user that the tracked event belongs to.
    - `time` string, date-time, required — The ISO 8601 timestamp of the event.

## Other responses

- `400` — Bad request: malformed body or missing required parameters
- `401` — Unauthorized request: invalid or missing API key
- `500` — Internal server error: unexpected error

---

[API](https://skmtc.net/permutive/apis/custom-cohort-segmentation-api.md) · [All operations](https://skmtc.net/permutive/apis/custom-cohort-segmentation-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/permutive/custom-cohort-segmentation-api/versions/9fb06b4e8a44/schema)