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.
It’s important to note that Permutive enforces event schemas to ensure data consistency and validity.If an event is tracked that does not match the expected schema for the event type, it will be rejected and a 400 error will be returned. Where Permutive hasn’t received an event type before, it will infer the event’s schema.Event schemas are viewable in the Permutive Dashboard. To migrate an event schema, please email support.
Event size limit
The size of an event’s properties JSON object is limited to 950 KB to ensure platform performance.If an event exceeds this size limit, it will be rejected and a 400 error will be returned.
Time attributes
When streaming in data in real-time (e.g. from within an app), Permutive sets a time attribute for events to the current time in UTC.
Authorizations
HeaderParameter
X-API-Key
string
header
required
Query Parameters
enrich
boolean
This boolean parameter determines whether to enrich the event with geo, ISP, and natural language processing data. By default, this is set to true.
sdkp
boolean
This boolean parameter is used to describe whether the event originated from a Permutive SDK on a client's device, where true denotes the event was from an SDK and false denotes an out-of-SDK event.
By default, this parameter is set to true. If you are interacting with this endpoint directly, rather than through a Permutive SDK, please set this parameter to false.
Body
application/json
You must provide either a user_idor a non-empty list aliases of prioritized aliases to specify the user that the event belongs to.
If a user_id is provided, it will be used directly to identify the user, ignoring any aliases provided. If only aliases are provided and none match, a new user ID is generated and the aliases are synced to it.
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_].
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 · object[]
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.
Minimum array length: 1
Show child attributes
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
JSON · object
The properties that belong to this event. These properties must adhere to the specific schema configured for this event collection.
Response
Event created successfully
Event response (regular)
Event response (unenriched)
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
JSON · object
The properties that belong to the tracked event. These properties adhere to the specific schema configured for this event collection.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Permutive","colors":{"primary":"#ff5e99","light":"#f3eefe","dark":"#632ef5"},"logo":{"light":"https://mintcdn.com/permutive/zX9G7jjpccuZZlEf/logo/permutive-logo-light.svg?fit=max\u0026auto=format\u0026n=zX9G7jjpccuZZlEf\u0026q=85\u0026s=ae940c2b1c2eb923f6344b583fef176c","dark":"https://mintcdn.com/permutive/zX9G7jjpccuZZlEf/logo/permutive-logo-dark.svg?fit=max\u0026auto=format\u0026n=zX9G7jjpccuZZlEf\u0026q=85\u0026s=6406296261c92b204e6a6a9f8cca5676"},"favicon":"https://mintcdn.com/permutive/pNhz39ducTVcQczh/favicon.svg?fit=max\u0026auto=format\u0026n=pNhz39ducTVcQczh\u0026q=85\u0026s=a80278bd668352096f35034b78398cb5","navbar":{"primary":{"type":"button","label":"Dashboard","href":"https://dash.permutive.com"}},"footer":{"socials":{"x":"https://x.com/permutive","github":"https://github.com/permutive","linkedin":"https://uk.linkedin.com/company/permutive"}},"styling":{"codeblocks":"dark","latex":true},"variables":{"android_core_release_version":"1.16.0","android_google_ads_release_version":"2.2.0","android_appnexus_release_version":"1.7.0"},"navigation":{"global":{"anchors":[{"anchor":"Support","icon":"life-ring","href":"mailto:technical-services@permutive.com"},{"anchor":"Status","icon":"signal","href":"https://status.permutive.com"},{"anchor":"Changelog","icon":"megaphone","href":"https://changelog.permutive.com"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"permutive","hasAudioNarration":false,"actualSubdomain":"permutive","customDomains":["docs.permutive.com"],"gitSource":{"type":"github","owner":"permutive","repo":"permutive-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6afc2afc2d447c3b84b9c090","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Guides","count":145},{"language":"default","tag":"Integrations","count":123},{"language":"default","tag":"Platform","count":102},{"language":"default","tag":"Deployment","count":66},{"language":"default","tag":"Signals","count":48},{"language":"default","tag":"Mobile","count":40},{"language":"default","tag":"Cohorts","count":37},{"language":"default","tag":"APIs","count":35},{"language":"default","tag":"Advertising","count":25},{"language":"default","tag":"Connectivity","count":22}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"styles/custom.css","content":"pre,pre[class*=\"shiki\"],[data-rehype-pretty-code-fragment] pre,div[data-rehype-pretty-code-fragment] pre,figure[data-rehype-pretty-code-figure] pre{background-color:#1A1A1A!important}pre span[style],code span[style]{color:var(--shiki-dark)!important}:not(pre)>code{padding:0.2em 0.4em;border-radius:3px}html:not(.dark) :not(pre)>code{background-color:#EDEDED!important;color:#FA8784!important}html.dark :not(pre)>code{background-color:#1A1A1A!important;color:#F7D0E2!important}[data-callout-type=\"note\"]{border-color:#5BB5E0!important}[data-callout-type=\"note\"] svg{color:#5BB5E0!important}[data-callout-type=\"tip\"]{border-color:#9B7EE8!important}[data-callout-type=\"tip\"] svg{color:#9B7EE8!important}[data-callout-type=\"info\"]{border-color:#9CA3AF!important}[data-callout-type=\"info\"] svg{color:#6B7280!important}[data-callout-type=\"warning\"]{border-color:#E8956A!important}[data-callout-type=\"warning\"] svg{color:#E8956A!important}html:not(.dark) [data-callout-type=\"note\"]{background-color:rgba(199, 232, 249, 0.4)!important}html:not(.dark) [data-callout-type=\"tip\"]{background-color:rgba(203, 182, 255, 0.4)!important}html:not(.dark) [data-callout-type=\"info\"]{background-color:rgba(237, 237, 237, 0.5)!important}html:not(.dark) [data-callout-type=\"warning\"]{background-color:rgba(249, 193, 168, 0.4)!important}html:not(.dark) :is([data-callout-type=\"note\"],[data-callout-type=\"tip\"],[data-callout-type=\"info\"],[data-callout-type=\"warning\"]) [data-component-part=\"callout-content\"]{color:#1A1A1A!important}html.dark [data-callout-type=\"note\"]{background-color:rgba(91, 181, 224, 0.12)!important}html.dark [data-callout-type=\"tip\"]{background-color:rgba(155, 126, 232, 0.14)!important}html.dark [data-callout-type=\"info\"]{background-color:rgba(156, 163, 175, 0.12)!important}html.dark [data-callout-type=\"info\"] svg{color:#9CA3AF!important}html.dark [data-callout-type=\"warning\"]{background-color:rgba(232, 149, 106, 0.12)!important}html.dark :is([data-callout-type=\"note\"],[data-callout-type=\"tip\"],[data-callout-type=\"info\"],[data-callout-type=\"warning\"]) [data-component-part=\"callout-content\"]{color:#E5E7EB!important}html.dark [data-callout-type] :not(pre)>code{background-color:rgba(255, 255, 255, 0.1)!important;color:#F7D0E2!important}.agent-chat-user{display:flex;justify-content:flex-end;margin:1.25rem 0}.agent-chat-user-bubble{max-width:85%;padding:0.75rem 1rem;border-radius:1rem;background-color:#F0F0F0;color:#1A1A1A}.agent-chat-user-bubble>p{margin:0.4rem 0}.agent-chat-agent{margin:1.25rem 0;padding:1rem 1.25rem 0.75rem;border:1px solid #E5E5E5;border-radius:1rem}.agent-chat-tools{font-size:0.8rem;color:#8A8A8A;margin-bottom:0.5rem}html.dark .agent-chat-user-bubble{background-color:#2A2A2A;color:#EDEDED}html.dark .agent-chat-agent{border-color:#333333}.agent-chat-conversation{display:grid;grid-template-columns:minmax(0, 1fr) 16.5rem;column-gap:5.75rem;margin:2rem -22.25rem 3rem 0}body:has(.agent-chat-conversation) #content-side-layout{pointer-events:none}body:has(.agent-chat-conversation) #table-of-contents-layout{pointer-events:auto}.agent-chat-conversation>.agent-chat-turn{grid-column:1;min-width:0;margin-bottom:1.5rem}.agent-chat-conversation{position:relative}.agent-chat-conversation>.agent-chat-rail{position:absolute;top:0;right:0;bottom:calc(-1 * var(--agent-chat-rail-extend, 0px));width:16.5rem}.agent-chat-turn-label{display:none}.agent-chat-rail-list{position:sticky;top:calc(9.5rem + var(--agent-chat-toc-height, 15rem) + 1.5rem);max-height:calc(100vh - 9.5rem - var(--agent-chat-toc-height, 15rem) - 2.5rem);overflow-y:auto;overscroll-behavior:contain;scrollbar-width:none;list-style:none;margin:0;padding:0 0 0 1.25rem}.agent-chat-rail-list::-webkit-scrollbar{display:none}.agent-chat-rail-list::before{content:\"\";position:absolute;left:0;top:0;bottom:0;width:3px;border-radius:3px;background-color:#E5E5E5}.agent-chat-rail-step{position:relative}.agent-chat-rail-step::before{content:\"\";position:absolute;left:-1.25rem;top:0;bottom:0;width:3px;border-radius:3px;background-color:#ff5e99;opacity:0;transition:opacity 0.25s ease}.agent-chat-rail-step.is-active::before{opacity:1}.agent-chat-rail-step{margin:0 0 0.9rem;padding:0;font-size:0.875rem;opacity:0.45;transition:opacity 0.3s ease}.agent-chat-rail-step::marker{content:none}.agent-chat-rail-step.is-done{opacity:0.65}.agent-chat-rail-step.is-active{opacity:1}.agent-chat-rail-step .agent-chat-note-body{display:grid;grid-template-rows:0fr;overflow:hidden;transition:grid-template-rows 0.3s ease}.agent-chat-rail-step .agent-chat-note-body>*{min-height:0}.agent-chat-rail-step.is-active .agent-chat-note-body{grid-template-rows:1fr}.agent-chat-note-title{font-weight:600;margin:0.15rem 0 0.4rem}.agent-chat-note-body code{font-size:0.75rem}html.dark .agent-chat-rail-list::before{background-color:#333333}@media (max-width: 1279px){.agent-chat-conversation{grid-template-columns:minmax(0, 1fr);margin-right:0}.agent-chat-conversation>.agent-chat-rail{position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%)}.agent-chat-rail-list{position:relative;top:auto;max-height:none;overflow:visible;-webkit-mask-image:none!important;mask-image:none!important}.agent-chat-rail-step::before{display:none}.agent-chat-rail-step,.agent-chat-rail-step.is-done{opacity:1}.agent-chat-rail-step .agent-chat-note-body{grid-template-rows:1fr}.agent-chat-turn-label{display:none}.agent-chat-conversation{padding-top:var(--agent-chat-floating-space, 0px)}}.agent-chat-excerpt{-webkit-mask-image:linear-gradient(to bottom, black calc(100% - 3rem), transparent);mask-image:linear-gradient(to bottom, black calc(100% - 3rem), transparent)}.agent-chat-body:has(details[open]) .agent-chat-excerpt{display:none}.agent-chat-full>summary{cursor:pointer;list-style:none;font-size:0.8rem;font-weight:600;color:#ff5e99;text-align:center;padding:0.25rem 0}.agent-chat-full>summary::-webkit-details-marker{display:none}.agent-chat-full>summary::after{content:\"Show full response ↓\"}.agent-chat-full[open]>summary::after{content:\"Show less ↑\"}.agent-chat-chart{margin:1rem 0;padding:1rem;border-radius:0.75rem;background-color:#F7F7F7}.agent-chat-chart-caption{margin-bottom:0.75rem}.agent-chat-chart-title{font-weight:600;font-size:0.9rem}.agent-chat-chart-unit{font-size:0.75rem;color:#8A8A8A}.agent-chat-chart-row{display:grid;grid-template-columns:9.5rem minmax(0, 1fr) 4.5rem;align-items:center;gap:0.75rem;font-size:0.8rem;margin:0.3rem 0}.agent-chat-chart-label{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.agent-chat-chart-track{height:0.9rem}.agent-chat-chart-bar{display:block;height:100%;border-radius:0 4px 4px 0;background-color:#ff5e99}.agent-chat-chart-value{text-align:right;font-variant-numeric:tabular-nums}html.dark .agent-chat-chart{background-color:#222222}@media (max-width: 640px){.agent-chat-chart-row{grid-template-columns:7rem minmax(0, 1fr) 4rem;gap:0.5rem}}.agent-chat-user-bubble [data-as=\"p\"],.agent-chat-body [data-as=\"p\"]{display:block;margin:0.6rem 0}.agent-chat-user-bubble [data-as=\"p\"]:first-child{margin-top:0}.agent-chat-user-bubble [data-as=\"p\"]:last-child{margin-bottom:0}.agent-chat-conversation .agent-chat-user,.agent-chat-conversation .agent-chat-agent{margin:0.5rem 0}.agent-chat-user-bubble,.agent-chat-agent,.agent-chat-attachment{transition:box-shadow 0.25s ease}.agent-chat-turn.is-current .agent-chat-user-bubble,.agent-chat-turn.is-current .agent-chat-agent,.agent-chat-turn.is-current .agent-chat-attachment{box-shadow:0 0 0 2px #ff5e99}.agent-chat-connector{position:fixed;inset:0;z-index:20;pointer-events:none;overflow:visible}.agent-chat-connector path{fill:none;stroke:#ff5e99;stroke-width:2;stroke-linejoin:round}.agent-chat-body table{font-size:0.8125rem}.agent-chat-body table th,.agent-chat-body table td{min-width:0;white-space:normal}.agent-chat-tools a{border-bottom:none}.agent-chat-conversation>.agent-chat-agent{grid-column:1;min-width:0;margin:0.5rem 0 1.5rem}.agent-chat-part{margin:0 -0.75rem;padding:0.25rem 0.75rem;border-radius:0.6rem;transition:box-shadow 0.25s ease}.agent-chat-turn.agent-chat-part.is-current{box-shadow:0 0 0 2px #ff5e99}.agent-chat-attachment-row{display:flex;justify-content:flex-end;margin:0.5rem 0 0.3rem}.agent-chat-conversation>.agent-chat-turn:has(>.agent-chat-attachment-row){margin-bottom:0}.agent-chat-attachment{display:inline-flex;align-items:center;gap:0.5rem;padding:0.5rem 0.75rem;border:1px solid #E5E5E5;border-radius:0.75rem;background:none;font-size:0.8125rem;cursor:zoom-in}.agent-chat-attachment:hover{border-color:#ff5e99}.agent-chat-attachment-kind{font-size:0.65rem;font-weight:600;padding:0.1rem 0.35rem;border-radius:0.3rem;background-color:#F0F0F0;color:#6B6B6B}.agent-chat-document{position:fixed;inset:0;margin:auto;height:fit-content;width:min(52rem, calc(100vw - 2rem));max-height:calc(100vh - 4rem);padding:0;border:1px solid #E5E5E5;border-radius:0.75rem;overflow:auto;background-color:#F7F7F7}.agent-chat-document::backdrop{background-color:rgb(0 0 0 / 0.4)}.agent-chat-document-header{position:sticky;top:0;display:flex;justify-content:space-between;align-items:center;padding:0.6rem 1rem;border-bottom:1px solid #E5E5E5;background-color:#FFFFFF;font-size:0.875rem;font-weight:600}.agent-chat-document-header button{background:none;border:none;cursor:pointer;font-size:1rem;color:#6B6B6B}.agent-chat-document-pages{display:flex;flex-direction:column;gap:1rem;padding:1rem}.agent-chat-document-pages img{width:100%;margin:0;border-radius:0.25rem;box-shadow:0 1px 4px rgb(0 0 0 / 0.15)}html.dark .agent-chat-attachment,html.dark .agent-chat-document,html.dark .agent-chat-document-header{border-color:#333333}html.dark .agent-chat-document{background-color:#1A1A1A}html.dark .agent-chat-document-header{background-color:#222222}html.dark .agent-chat-attachment-kind{background-color:#2A2A2A;color:#AAAAAA}.agent-chat-doc-link{display:block;margin-top:0.4rem;padding:0;border:none;background:none;font-size:0.8125rem;font-weight:600;color:#ff5e99;cursor:pointer}.agent-chat-doc-link:hover{text-decoration:underline}.agent-chat-document-annotated .agent-chat-document-header{background-color:#FFF0F5;border-bottom-color:#FFD1E1;color:#B3245B}.agent-chat-document-annotated .agent-chat-document-pages img{box-shadow:none;border:1px solid #E5E5E5}html.dark .agent-chat-document-annotated .agent-chat-document-header{background-color:#3A1A27;border-bottom-color:#5A2A3D;color:#FF9EC1}.agent-chat-document-annotated .agent-chat-document-pages{gap:0;margin:1rem;padding:1rem;border:1px solid #E5E5E5;border-radius:0.25rem;background-color:#FFFFFF}.agent-chat-document-annotated .agent-chat-document-pages img{border:none;border-radius:0}.agent-chat-document-annotated .agent-chat-document-pages img+img{margin-top:0.75rem;padding-top:0.75rem;border-top:1px dashed #D0D0D0}.agent-chat-attachment-output{justify-content:flex-start;margin:1rem 0 0.5rem}.agent-chat-document-wide{width:min(90rem, calc(100vw - 4rem))}.agent-chat-attachment-label{display:inline-flex;align-items:center;gap:0.5rem;min-width:0}.agent-chat-attachment-card{flex-direction:column;align-items:stretch;gap:0.5rem;width:33%;min-width:14rem;padding:0.5rem 0.5rem 0.6rem}.agent-chat-attachment-card .agent-chat-attachment-thumb{display:block;width:100%;margin:0;border:1px solid #EDEDED;border-radius:0.4rem}.agent-chat-attachment-card .agent-chat-attachment-label{padding:0 0.25rem}.agent-chat-attachment-card .agent-chat-attachment-name{text-align:left}.agent-chat-attachment-card .agent-chat-attachment-kind{margin-left:auto}html.dark .agent-chat-attachment-card .agent-chat-attachment-thumb{border-color:#333333}.agent-chat-document-wide .agent-chat-document-pages img{width:auto;max-width:100%;max-height:calc(100vh - 10rem);margin:0 auto}.agent-chat-card-tags{display:flex;flex-wrap:wrap;gap:0.35rem;margin-top:0.6rem}.agent-chat-card-tags>span{padding:0.1rem 0.45rem;border-radius:0.3rem;background-color:#FFF0F5;color:#B3245B;font-size:0.7rem;font-weight:600}html.dark .agent-chat-card-tags>span{background-color:#3A1A27;color:#FF9EC1}a.agent-chat-note-title{display:block;color:inherit;text-decoration:none;border-bottom:none;cursor:pointer}a.agent-chat-note-title:hover{color:#ff5e99}.agent-chat-turn{scroll-margin-top:9rem}.agent-chat-floating{position:fixed;z-index:30;box-sizing:border-box;padding:0.75rem 1rem;border:1px solid #E5E5E5;border-left:3px solid #ff5e99;border-radius:0.6rem;background-color:#FFFFFF;box-shadow:0 6px 20px rgb(0 0 0 / 0.08);font-size:0.8125rem;line-height:1.45;opacity:0;visibility:hidden;transition:opacity 0.2s ease, visibility 0.2s}.agent-chat-floating.is-visible{opacity:1;visibility:visible}.agent-chat-floating-title{font-weight:600;margin-bottom:0.25rem}.agent-chat-floating-body code{font-size:0.75rem}.agent-chat-floating .agent-chat-doc-link{margin-top:0.3rem}html.dark .agent-chat-floating{background-color:#1A1A1A;border-color:#333333;border-left-color:#ff5e99}@media (min-width: 1280px){.agent-chat-floating{display:none}}.agent-chat-body table code{white-space:nowrap}"}]}
{"page":{"pagePath":"api/events/track","slug":"/api/events/track","pageMetadata":{"title":"Track an event","openapi":"POST /events","description":"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.","href":"/api/events/track"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"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.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,..._provideComponents(),...props.components},{Heading}=_components;if(!Heading)_missingMdxReference(`Heading`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`2`,id:`event-schema`,children:`Event schema`}),`\n`,_jsx(_components.p,{children:`It’s important to note that Permutive enforces event schemas to ensure data consistency and validity.`}),`\n`,_jsxs(_components.p,{children:[`If an event is tracked that does not match the expected schema for the event type, it will be rejected and a `,_jsx(_components.code,{children:`400`}),` error will be returned. Where Permutive hasn’t received an event type before, it will infer the event’s schema.`]}),`\n`,_jsxs(_components.p,{children:[`Event schemas are viewable in the `,_jsx(_components.a,{href:`https://dash.permutive.com`,children:`Permutive Dashboard`}),`. To migrate an event schema, please `,_jsx(_components.a,{href:`mailto:support@permutive.com`,children:`email support`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`event-size-limit`,children:`Event size limit`}),`\n`,_jsxs(_components.p,{children:[`The size of an event’s `,_jsx(_components.code,{children:`properties`}),` JSON object is limited to 950 KB to ensure platform performance.`]}),`\n`,_jsx(_components.p,{children:`If an event exceeds this size limit, it will be rejected and a 400 error will be returned.`}),`\n`,_jsx(Heading,{level:`2`,id:`time-attributes`,children:`Time attributes`}),`\n`,_jsx(_components.p,{children:`When streaming in data in real-time (e.g. from within an app), Permutive sets a time attribute for events to the current time in UTC.`})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"codeStyling":"dark","config":{},"pageMetadata":{"title":"Track an event","openapi":"POST /events","description":"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.","href":"/api/events/track"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Event schema","slug":"event-schema","depth":2,"children":[]},{"title":"Event size limit","slug":"event-size-limit","depth":2,"children":[]},{"title":"Time attributes","slug":"time-attributes","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/permutive/9a9f86ed1fb0eb1f/agent-chat-rail.js"],"openApiReferenceData":{"operation":{"tags":["v2.0"],"summary":"Track an event","description":"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.","operationId":"createEvent","parameters":["f45def9e-3b6a-405e-917a-9e36abe712bd","90e09242-d730-4e3a-a4d2-8d3dc632e8e9"],"requestBody":"17ead018-e9fc-4d77-a334-bb45e454fa96","responses":{"201":"10d467af-a2b9-4700-b039-50a9fd53869b","400":"95cee06f-a35f-4ea1-9dc8-470ead9bc56d","401":"1548edbb-56eb-4e90-993b-91abb244fc48","500":"b248ac1e-159d-4284-9678-daa94463e370"},"security":["7d78d3ef-f8c9-4db3-9c66-160bae98b6aa","765fe385-97a1-4649-ac52-878c666e3d60"],"method":"post","type":"path","servers":["ebe8e5f6-2e3b-4aeb-9d9d-5dad7a3ed755"],"path":"/events","baseUrlOptions":["https://api.permutive.app/v2.0"],"title":"Track an event","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"f45def9e-3b6a-405e-917a-9e36abe712bd":{"name":"enrich","in":"query","description":"This boolean parameter determines whether to enrich the event with geo, ISP, and natural language processing data. By default, this is set to `true`.","required":false,"schema":{"type":"boolean","isRequired":false,"description":"This boolean parameter determines whether to enrich the event with geo, ISP, and natural language processing data. By default, this is set to `true`.","uniqueKey":"","typeLabel":"boolean"}},"90e09242-d730-4e3a-a4d2-8d3dc632e8e9":{"name":"sdkp","in":"query","description":"This boolean parameter is used to describe whether the event originated from a Permutive SDK on a client's device, where `true` denotes the event was from an SDK and `false` denotes an out-of-SDK event.\n\n By default, this parameter is set to `true`. If you are interacting with this endpoint directly, rather than through a Permutive SDK, please set this parameter to `false`.","required":false,"schema":{"type":"boolean","isRequired":false,"description":"This boolean parameter is used to describe whether the event originated from a Permutive SDK on a client's device, where `true` denotes the event was from an SDK and `false` denotes an out-of-SDK event.\n\n By default, this parameter is set to `true`. If you are interacting with this endpoint directly, rather than through a Permutive SDK, please set this parameter to `false`.","uniqueKey":"","typeLabel":"boolean"}}},"requestBody":{"description":"You must provide **either** a `user_id` **or** a non-empty list `aliases` of prioritized aliases to specify the user that the event belongs to.\n\n If a `user_id` is provided, it will be used directly to identify the user, ignoring any aliases provided. If only aliases are provided and none match, a new user ID is generated and the aliases are synced to it.","content":{"application/json":{"schema":{"title":"PostEvent","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"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_]`.","isRequired":true,"uniqueKey":"name","typeLabel":"string"},"user_id":{"type":"string","format":"uuid","description":"The Permutive user ID of the user that the event belongs to.\n\n If you do not provide a user ID, you must provide a non-empty list of aliases in the `aliases` field.","uniqueKey":"user_id","typeLabel":"string\u003cuuid>"},"aliases":{"type":"array","items":{"title":"PrioritizedAlias","type":"object","required":["priority","tag","id"],"properties":{"priority":{"type":"integer","format":"int32","description":"The priority of the alias, where `0` is the highest priority.","isRequired":true,"uniqueKey":"aliases.items.[INDEX].priority","typeLabel":"integer\u003cint32>"},"tag":{"type":"string","description":"The tag is a string used to identify the type of alias, e.g. `email_sha256` or `myInternalID`.","isRequired":true,"uniqueKey":"aliases.items.[INDEX].tag","typeLabel":"string"},"id":{"type":"string","description":"The identifier for the alias, e.g. `user@example.com` or `1234567890`.","isRequired":true,"uniqueKey":"aliases.items.[INDEX].id","typeLabel":"string"}},"uniqueKey":"aliases.items.[INDEX]","typeLabel":"PrioritizedAlias · object"},"minItems":1,"description":"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.\n\n Prioritized aliases allow customers to express which identifiers they consider most reliable or authoritative for resolving user identities.\n\n 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.","uniqueKey":"aliases","typeLabel":"PrioritizedAlias · object[]"},"view_id":{"type":"string","format":"uuid","description":"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.","uniqueKey":"view_id","typeLabel":"string\u003cuuid>"},"session_id":{"type":"string","format":"uuid","description":"The identifier for the session in which the event is taking place. This is used to group events within a user session.","uniqueKey":"session_id","typeLabel":"string\u003cuuid>"},"segments":{"type":"array","items":{"type":"integer","uniqueKey":"segments.items.[INDEX]","typeLabel":"integer"},"description":"The list of segment codes that the user belonged to at the time of the event.","uniqueKey":"segments","typeLabel":"integer[]"},"cohorts":{"type":"array","items":{"type":"string","uniqueKey":"cohorts.items.[INDEX]","typeLabel":"string"},"description":"The list of cohort IDs that the user belonged to at the time of the event.","uniqueKey":"cohorts","typeLabel":"string[]"},"properties":{"type":"object","title":"JSON","description":"The properties that belong to this event. These properties must adhere to the specific schema configured for this event collection.","uniqueKey":"properties","typeLabel":"JSON · object"}},"uniqueKey":"","typeLabel":"PostEvent · object"},"examples":{"User ID request":{"title":"User ID request","summary":"User ID request","description":"A request to create an event for a user with a user ID.","value":{"name":"Pageview","user_id":"2008c38f-dece-4570-976d-87593ed001c3","view_id":"a55a9c8b-4a0b-4fe7-99a9-170624850501","session_id":"1d145310-1338-4ff7-96dd-e6128f54cbe5","properties":{"my_string":"hello, world!","my_number":42,"my_boolean":true,"my_object":{"inner_property_string":"nested value","inner_property_integer":69}}}},"Aliases request":{"title":"Aliases request","summary":"Aliases request","description":"A request to create an event for a user with aliases.","value":{"name":"Pageview","aliases":[{"priority":0,"tag":"email_sha256","id":"user@example.com"},{"priority":1,"tag":"some-third-party-id-provider","id":"1234567890"}],"view_id":"a55a9c8b-4a0b-4fe7-99a9-170624850501","session_id":"1d145310-1338-4ff7-96dd-e6128f54cbe5","properties":{"my_string":"hello, world!","my_number":42,"my_boolean":true,"my_object":{"inner_property_string":"nested value","inner_property_integer":69}}}}},"exampleType":"examples"}},"required":true,"exampleType":"examples"},"responses":{"10d467af-a2b9-4700-b039-50a9fd53869b":{"description":"Event created successfully","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Event response (regular)","required":["user_id"],"properties":{"user_id":{"type":"string","format":"uuid","description":"The Permutive user ID of the user that the tracked event belongs to.","isRequired":true,"uniqueKey":"oneOf.0.user_id","typeLabel":"string\u003cuuid>"},"name":{"type":"string","description":"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_]`.","uniqueKey":"oneOf.0.name","typeLabel":"string"},"time":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of the event.","uniqueKey":"oneOf.0.time","typeLabel":"string\u003cdate-time>"},"view_id":{"type":"string","format":"uuid","description":"The identifier for the view in which the tracked event took place.","uniqueKey":"oneOf.0.view_id","typeLabel":"string\u003cuuid>"},"session_id":{"type":"string","format":"uuid","description":"The identifier for the session in which the tracked event took place.","uniqueKey":"oneOf.0.session_id","typeLabel":"string\u003cuuid>"},"segments":{"type":"array","items":{"type":"integer","uniqueKey":"oneOf.0.segments.items.[INDEX]","typeLabel":"integer"},"description":"The list of segment codes that the user belonged to at the time the event was tracked.","uniqueKey":"oneOf.0.segments","typeLabel":"integer[]"},"cohorts":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.cohorts.items.[INDEX]","typeLabel":"string"},"description":"The list of cohort IDs that the user belonged to at the time the event was tracked.","uniqueKey":"oneOf.0.cohorts","typeLabel":"string[]"},"properties":{"type":"object","title":"JSON","description":"The properties that belong to the tracked event. These properties adhere to the specific schema configured for this event collection.","uniqueKey":"oneOf.0.properties","typeLabel":"JSON · object"}},"uniqueKey":"oneOf.0","typeLabel":"Event response (regular) · object"},{"type":"object","title":"Event response (unenriched)","required":["user_id","time"],"properties":{"user_id":{"type":"string","format":"uuid","description":"The Permutive user ID of the user that the tracked event belongs to.","isRequired":true,"uniqueKey":"oneOf.1.user_id","typeLabel":"string\u003cuuid>"},"time":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of the event.","isRequired":true,"uniqueKey":"oneOf.1.time","typeLabel":"string\u003cdate-time>"}},"uniqueKey":"oneOf.1","typeLabel":"Event response (unenriched) · object"}],"uniqueKey":"","typeLabel":"Event response (regular) · object | Event response (unenriched) · object"},"examples":{"Enriched":{"title":"Enriched","summary":"Full response when enrich=true","value":{"name":"Pageview","user_id":"2008c38f-dece-4570-976d-87593ed001c3","time":"2026-01-01T12:00:00.000Z","view_id":"a55a9c8b-4a0b-4fe7-99a9-170624850501","session_id":"1d145310-1338-4ff7-96dd-e6128f54cbe5","properties":{"my_string":"hello, world!","my_number":42,"my_boolean":true,"my_object":{"inner_property_string":"nested value","inner_property_integer":69}}}},"Non-enriched":{"title":"Non-enriched","summary":"Minimal response when enrich=false","value":{"user_id":"2008c38f-dece-4570-976d-87593ed001c3","time":"2026-01-01T12:00:00.000Z"}}},"exampleType":"examples"}},"exampleType":"examples"},"95cee06f-a35f-4ea1-9dc8-470ead9bc56d":{"description":"Bad request: malformed body or missing required parameters","content":{"application/json":{"schema":{"title":"HttpErrorResponse","type":"object","required":["request_id","error"],"properties":{"request_id":{"title":"RequestId","type":"string","format":"uuid","description":"A unique identifier for the request that caused the error.","isRequired":true,"uniqueKey":"request_id","typeLabel":"string\u003cuuid>"},"error":{"type":"object","description":"Details of the error that occurred.","required":["status","code","message","docs"],"properties":{"status":{"type":"string","enum":["BadRequest","Unauthorized","NotFound","Conflict","Gone","InternalServerError","Forbidden"],"description":"The type of error that occurred.","isRequired":true,"uniqueKey":"error.status","typeLabel":"enum\u003cstring>"},"code":{"type":"integer","format":"int32","description":"A numeric code that identifies the error.","isRequired":true,"uniqueKey":"error.code","typeLabel":"integer\u003cint32>"},"message":{"type":"string","description":"A human-readable message describing the error.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docs":{"type":"string","format":"uri","description":"A URL to the documentation for the error.","isRequired":true,"uniqueKey":"error.docs","typeLabel":"string\u003curi>"},"cause":{"type":"string","description":"A human-readable message describing additional details of the error.","uniqueKey":"error.cause","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"HttpErrorResponse · object"},"examples":{"Invalid parameters":{"title":"Invalid parameters","summary":"Invalid parameters","value":{"request_id":"550e8400-e29b-41d4-a716-446655440000","error":{"status":"BadRequest","code":1000,"message":"The values of one or more parameters are invalid.","docs":"https://docs.permutive.com/api/errors"}}},"Missing request body":{"title":"Missing request body","summary":"Missing request body","value":{"request_id":"550e8400-e29b-41d4-a716-446655440000","error":{"status":"BadRequest","code":1003,"message":"A request body was expected but not found.","docs":"https://docs.permutive.com/api/errors"}}}},"exampleType":"examples"}},"exampleType":"examples"},"1548edbb-56eb-4e90-993b-91abb244fc48":{"description":"Unauthorized request: invalid or missing API key","content":{"application/json":{"schema":{"title":"HttpErrorResponse","type":"object","required":["request_id","error"],"properties":{"request_id":{"title":"RequestId","type":"string","format":"uuid","description":"A unique identifier for the request that caused the error.","isRequired":true,"uniqueKey":"request_id","typeLabel":"string\u003cuuid>"},"error":{"type":"object","description":"Details of the error that occurred.","required":["status","code","message","docs"],"properties":{"status":{"type":"string","enum":["BadRequest","Unauthorized","NotFound","Conflict","Gone","InternalServerError","Forbidden"],"description":"The type of error that occurred.","isRequired":true,"uniqueKey":"error.status","typeLabel":"enum\u003cstring>"},"code":{"type":"integer","format":"int32","description":"A numeric code that identifies the error.","isRequired":true,"uniqueKey":"error.code","typeLabel":"integer\u003cint32>"},"message":{"type":"string","description":"A human-readable message describing the error.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docs":{"type":"string","format":"uri","description":"A URL to the documentation for the error.","isRequired":true,"uniqueKey":"error.docs","typeLabel":"string\u003curi>"},"cause":{"type":"string","description":"A human-readable message describing additional details of the error.","uniqueKey":"error.cause","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"HttpErrorResponse · object"},"examples":{"Invalid API key":{"title":"Invalid API key","summary":"Invalid API key","value":{"request_id":"550e8400-e29b-41d4-a716-446655440000","error":{"status":"Unauthorized","code":2000,"message":"The API key provided is invalid.","docs":"https://docs.permutive.com/api/errors"}}},"Missing authentication":{"title":"Missing authentication","summary":"Missing authentication","value":{"request_id":"550e8400-e29b-41d4-a716-446655440000","error":{"status":"Unauthorized","code":2004,"message":"The resource requires authentication, which was not supplied with the request.","docs":"https://docs.permutive.com/api/errors"}}}},"exampleType":"examples"}},"exampleType":"examples"},"b248ac1e-159d-4284-9678-daa94463e370":{"description":"Internal server error: unexpected error","content":{"application/json":{"schema":{"title":"HttpErrorResponse","type":"object","required":["request_id","error"],"properties":{"request_id":{"title":"RequestId","type":"string","format":"uuid","description":"A unique identifier for the request that caused the error.","isRequired":true,"uniqueKey":"request_id","typeLabel":"string\u003cuuid>"},"error":{"type":"object","description":"Details of the error that occurred.","required":["status","code","message","docs"],"properties":{"status":{"type":"string","enum":["BadRequest","Unauthorized","NotFound","Conflict","Gone","InternalServerError","Forbidden"],"description":"The type of error that occurred.","isRequired":true,"uniqueKey":"error.status","typeLabel":"enum\u003cstring>"},"code":{"type":"integer","format":"int32","description":"A numeric code that identifies the error.","isRequired":true,"uniqueKey":"error.code","typeLabel":"integer\u003cint32>"},"message":{"type":"string","description":"A human-readable message describing the error.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docs":{"type":"string","format":"uri","description":"A URL to the documentation for the error.","isRequired":true,"uniqueKey":"error.docs","typeLabel":"string\u003curi>"},"cause":{"type":"string","description":"A human-readable message describing additional details of the error.","uniqueKey":"error.cause","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"HttpErrorResponse · object"},"example":{"request_id":"550e8400-e29b-41d4-a716-446655440000","error":{"status":"InternalServerError","code":5000,"message":"An error of unspecified nature was encountered while processing your request. Feel free to get in touch with us at support@permutive.com referencing the Request ID.","docs":"https://docs.permutive.com/api/errors"}},"examples":{"Example":{"title":"Example","value":{"request_id":"550e8400-e29b-41d4-a716-446655440000","error":{"status":"InternalServerError","code":5000,"message":"An error of unspecified nature was encountered while processing your request. Feel free to get in touch with us at support@permutive.com referencing the Request ID.","docs":"https://docs.permutive.com/api/errors"}}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"7d78d3ef-f8c9-4db3-9c66-160bae98b6aa":{"Header":{"type":"apiKey","name":"X-API-Key","in":"header","scopes":[]}},"765fe385-97a1-4649-ac52-878c666e3d60":{"Parameter":{"type":"apiKey","name":"k","in":"query","scopes":[]}}},"servers":{"ebe8e5f6-2e3b-4aeb-9d9d-5dad7a3ed755":{"url":"https://api.permutive.app/v2.0"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","name":"X-API-Key","in":"header","scopes":[]},"schema":{"title":"X-API-Key","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"Header","name":"X-API-Key"}],"title":"Header"},{"schemes":[{"scheme":{"type":"apiKey","name":"k","in":"query","scopes":[]},"schema":{"title":"k","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"Parameter","name":"k"}],"title":"Parameter"}]},"originalFileLocation":"api/events/openapi.json"},"subdomain":"permutive","siteName":"Permutive","title":"Track an event - Permutive","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-01-28T21:14:33.327Z","originalFileLocation":"api/events/track.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"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.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Permutive\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Track an event - Permutive\">\u003cmeta data-mint-head property=\"og:description\" content=\"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.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Permutive\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.permutive.com/api/events/track\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://permutive.mintlify.site/_mintlify/api/og/v2?division=Events+API\u0026amp;title=Track+an+event\u0026amp;description=This+endpoint+creates+a+new+event+for+a+user%2C+persisting+the+event+in+Permutive+for+downstream+consumption%2C+such+as+for+segmentation%2C+insights%2C+or+routing+to+a+\u0026amp;theme=476d64e99ccc72d9df9ea1e6\u0026amp;signature=77a8700f13c7b86748696d233f0fac8214b3c0d6eb2a2704180613f9f798ba32\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Track an event - Permutive\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"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.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://permutive.mintlify.site/_mintlify/api/og/v2?division=Events+API\u0026amp;title=Track+an+event\u0026amp;description=This+endpoint+creates+a+new+event+for+a+user%2C+persisting+the+event+in+Permutive+for+downstream+consumption%2C+such+as+for+segmentation%2C+insights%2C+or+routing+to+a+\u0026amp;theme=476d64e99ccc72d9df9ea1e6\u0026amp;signature=77a8700f13c7b86748696d233f0fac8214b3c0d6eb2a2704180613f9f798ba32\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/permutive/_gGnYYOjUBeWUMY8/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Permutive\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#ff5e99\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.permutive.com/api/events/track\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api/events/track.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.permutive.com/#organization\",\"name\":\"Permutive\",\"url\":\"https://docs.permutive.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/permutive/zX9G7jjpccuZZlEf/logo/permutive-logo-light.svg?fit=max\u0026auto=format\u0026n=zX9G7jjpccuZZlEf\u0026q=85\u0026s=ae940c2b1c2eb923f6344b583fef176c\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.permutive.com#website\",\"name\":\"Permutive\",\"url\":\"https://docs.permutive.com\",\"publisher\":{\"@id\":\"https://docs.permutive.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.permutive.com/api/events/track#webpage\",\"url\":\"https://docs.permutive.com/api/events/track\",\"name\":\"Track an event\",\"description\":\"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.\",\"dateModified\":\"2026-01-28T21:14:33.327Z\",\"isPartOf\":{\"@id\":\"https://docs.permutive.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.permutive.com/api/events/track#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.permutive.com/api/events/track#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Events API\",\"item\":\"https://docs.permutive.com/api/events/introduction\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Track an event\",\"item\":\"https://docs.permutive.com/api/events/track\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.permutive.com/api/events/track#apireference\",\"headline\":\"Track an event\",\"name\":\"Track an event\",\"description\":\"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.\",\"url\":\"https://docs.permutive.com/api/events/track\",\"mainEntityOfPage\":{\"@id\":\"https://docs.permutive.com/api/events/track#webpage\"},\"dateModified\":\"2026-01-28T21:14:33.327Z\",\"publisher\":{\"@id\":\"https://docs.permutive.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.permutive.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Permutive\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Permutive\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api/events/track.md","siteName":"Permutive","nav":{"global":{"anchors":[{"anchor":"Support","icon":"life-ring","href":"mailto:technical-services@permutive.com"},{"anchor":"Status","icon":"signal","href":"https://status.permutive.com"},{"anchor":"Changelog","icon":"megaphone","href":"https://changelog.permutive.com"}]},"tabs":[{"tab":"Platform","pages":[{"title":"Platform","href":"/introduction"}]},{"tab":"Integrations","pages":[{"title":"Integrations","href":"/integrations/overview"}]},{"tab":"Guides","pages":[{"title":"Guides","href":"/guides/introduction"}]},{"tab":"APIs","groups":[{"group":"API Documentation","pages":[{"title":"Introduction","href":"/api/introduction"},{"title":"Authentication","href":"/api/authentication"},{"title":"Versioning","href":"/api/versioning"},{"title":"Requests \u0026 Responses","href":"/api/requests-and-responses"},{"title":"Errors","href":"/api/errors"}]},{"group":"Events API","pages":[{"title":"Introduction","description":"Capture behavioral and contextual data","href":"/api/events/introduction"},{"title":"Track an event","openapi":"POST /events","href":"/api/events/track"}]},{"group":"Identity API","pages":[{"title":"Introduction","description":"Manage device, user, and household identities","href":"/api/identity/introduction"},{"title":"Create a user ID","openapi":"POST /users","href":"/api/identity/create"},{"title":"Identify a user","openapi":"POST /identify","href":"/api/identity/identify"},{"title":"Retrieve identities","openapi":"GET /users/{userId}/aliases","href":"/api/identity/retrieve"}]},{"group":"Contextual API","pages":[{"title":"Introduction","href":"/api/contextual/introduction"},{"title":"Get Contextual Segments","api":"POST https://api.permutive.app/ctx/v1/segment","href":"/api/contextual/segment"}]},{"group":"Custom Cohort Segmentation API","pages":[{"title":"Introduction","href":"/api/ccs/introduction"},{"title":"Segment User","openapi":"POST /ccs/v1/segmentation","href":"/api/ccs/segmentation"},{"title":"Stateless Segmentation","openapi":"POST /ccs/v1/segmentation/stateless","href":"/api/ccs/segmentation-stateless"}]},{"group":"Cohorts API","pages":[{"title":"Introduction","href":"/api/cohorts/introduction"},{"title":"Cohort query format","href":"/api/cohorts/cohort-query-format"},{"title":"Create a cohort","openapi":"POST /v2/cohorts","href":"/api/cohorts/create-cohort"},{"title":"Retrieve individual cohort","openapi":"GET /v2/cohorts/{cohortId}","href":"/api/cohorts/get-cohort"},{"title":"Retrieve all cohorts","openapi":"GET /v2/cohorts","href":"/api/cohorts/get-cohorts"},{"title":"Update a cohort","openapi":"PATCH /v2/cohorts/{cohortId}","href":"/api/cohorts/update-cohort"},{"title":"Delete a cohort","openapi":"DELETE /v2/cohorts/{cohortId}","href":"/api/cohorts/delete-cohort"}]},{"group":"Taxonomy API","pages":[{"title":"Introduction","href":"/api/taxonomy/introduction"},{"title":"Get all imports","openapi":"GET /imports","href":"/api/taxonomy/get-imports"},{"title":"Retrieve an import","openapi":"GET /imports/{importId}","href":"/api/taxonomy/retrieve-import"},{"title":"Get all segments for an import","openapi":"GET /imports/{importId}/segments","href":"/api/taxonomy/get-segments-for-import"},{"title":"Get a segment by its public ID from an import","openapi":"GET /imports/{importId}/segments/{segmentId}","href":"/api/taxonomy/get-a-segment-by-id"},{"title":"Get a segment by its code from an import","openapi":"GET /imports/{importId}/segments/code/{segmentCode}","href":"/api/taxonomy/get-a-segment-by-code"},{"title":"Create a segment for an import","openapi":"POST /imports/{importId}/segments","href":"/api/taxonomy/create-a-segment"},{"title":"Update a segment by its public ID","openapi":"PATCH /imports/{importId}/segments/{segmentId}","href":"/api/taxonomy/update-a-segment-by-id"},{"title":"Update a segment by its code","openapi":"PATCH /imports/{importId}/segments/code/{segmentCode}","href":"/api/taxonomy/update-a-segment-by-code"},{"title":"Batch update segments","openapi":"PATCH /imports/{importId}/segments","href":"/api/taxonomy/batch-update"},{"title":"Delete a segment by its public ID","openapi":"DELETE /imports/{importId}/segments/{segmentId}","href":"/api/taxonomy/delete-a-segment-by-id"},{"title":"Delete a segment by its code","openapi":"DELETE /imports/{importId}/segments/code/{segmentCode}","href":"/api/taxonomy/delete-a-segment-by-code"}]}]},{"tab":"MCP","pages":[{"title":"MCP","href":"/api/mcp/introduction"}]}]},"basePath":"","title":"Track an event - Permutive","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CiUHMMOm.js","snippetPresets-BgfXU7Bw.js","utils-DWvOwgy_.js","style-to-object-BY3JEAdk.js","utils-BN7RXSMJ.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-CFw8bq89.js","conditional-requirements-CFM0id0Q.js","cloneDeep-CAwdfOU2.js","_Uint8Array-BJr8e-ZL.js","isObject-FP1Yky1u.js","ApiExamples-XX0UgMZK.js","usePlaygroundInputsStore-DXDFSa1V.js","shallow-CdX5aREi.js","isEqual-CoOaxexF.js","CodeSnippets-Cg2wpzWm.js","CodeSnippet-D_HwgQO_.js","getApiPlaygroundDisplay-CmCoerhe.js","Page-CVJ-f_k1.js","DynamicMarkdown-CQM9Bhbv.js","SectionHeading-DpbrP8nQ.js","icon-BPCgijHy.js","MethodPill-GQ8DuY0c.js","getPastedJson-Cb5mT31m.js","Check2Icon-a7bUI6e8.js","axios-CsQoIw0U.js","Markdown-CX2QY19L.js","AssistantPageLink-CY3bFglh.js","dist-Dl6_zDnT.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}