An event is an action a user takes on one of your environments, such as a site or app. Examples include viewing a page, clicking an article, pausing a video, or scrolling down a page/view.Events are a core data abstraction within the Permutive platform, typically used to capture user behavioral and contextual data. They are one the primary building inputs to building cohorts, activating audiences, and warehousing data for subsequent analysis.
Overview
The Events API provides one endpoint:
Track
Segment a user based on events and persist state for future requests.
{"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.4177","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":"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":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","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/introduction","slug":"/api/events/introduction","pageMetadata":{"title":"Introduction","description":"Capture behavioral and contextual data","href":"/api/events/introduction"},"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: \"Capture behavioral 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={p:`p`,..._provideComponents(),...props.components},{Card,CardGroup,Heading}=_components;if(!Card)_missingMdxReference(`Card`,true);if(!CardGroup)_missingMdxReference(`CardGroup`,true);if(!Heading)_missingMdxReference(`Heading`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`An event is an action a user takes on one of your environments, such as a site or app. Examples include viewing a page, clicking an article, pausing a video, or scrolling down a page/view.`}),`\n`,_jsx(_components.p,{children:`Events are a core data abstraction within the Permutive platform, typically used to capture user behavioral and contextual data. They are one the primary building inputs to building cohorts, activating audiences, and warehousing data for subsequent analysis.`}),`\n`,_jsx(Heading,{level:`2`,id:`overview`,children:`Overview`}),`\n`,_jsx(_components.p,{children:`The Events API provides one endpoint:`}),`\n`,_jsx(CardGroup,{cols:2,children:_jsx(Card,{title:`Track`,icon:`signal-stream`,href:`/api/events/track`,children:_jsx(_components.p,{children:`Segment a user based on events and persist state for future requests.`})})})]})}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":"Introduction","description":"Capture behavioral and contextual data","href":"/api/events/introduction"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Overview","slug":"overview","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/permutive/9a9f86ed1fb0eb1f/agent-chat-rail.js"],"subdomain":"permutive","siteName":"Permutive","title":"Introduction - Permutive","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-01-28T21:14:33.330Z","originalFileLocation":"api/events/introduction.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=\"Capture behavioral 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=\"Introduction - Permutive\">\u003cmeta data-mint-head property=\"og:description\" content=\"Capture behavioral 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/introduction\">\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=Introduction\u0026amp;description=Capture+behavioral+and+contextual+data\u0026amp;theme=476d64e99ccc72d9df9ea1e6\u0026amp;signature=374c0d0b78184190657b5f69774f0e37178f54cea22268f4837d3d331cad9d52\">\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=\"Introduction - Permutive\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Capture behavioral and contextual data\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://permutive.mintlify.site/_mintlify/api/og/v2?division=Events+API\u0026amp;title=Introduction\u0026amp;description=Capture+behavioral+and+contextual+data\u0026amp;theme=476d64e99ccc72d9df9ea1e6\u0026amp;signature=374c0d0b78184190657b5f69774f0e37178f54cea22268f4837d3d331cad9d52\">\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/introduction\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api/events/introduction.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/introduction#webpage\",\"url\":\"https://docs.permutive.com/api/events/introduction\",\"name\":\"Introduction\",\"description\":\"Capture behavioral and contextual data\",\"dateModified\":\"2026-01-28T21:14:33.330Z\",\"isPartOf\":{\"@id\":\"https://docs.permutive.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.permutive.com/api/events/introduction#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.permutive.com/api/events/introduction#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Permutive\",\"item\":\"https://docs.permutive.com\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Introduction\",\"item\":\"https://docs.permutive.com/api/events/introduction\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.permutive.com/api/events/introduction#article\",\"headline\":\"Introduction\",\"name\":\"Introduction\",\"description\":\"Capture behavioral and contextual data\",\"url\":\"https://docs.permutive.com/api/events/introduction\",\"mainEntityOfPage\":{\"@id\":\"https://docs.permutive.com/api/events/introduction#webpage\"},\"dateModified\":\"2026-01-28T21:14:33.330Z\",\"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/introduction.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","description":"How errors are represented in API responses","href":"/api/errors"}]},{"group":"Events API","pages":[{"title":"Introduction","href":"/api/events/introduction"},{"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"}]},{"group":"Identity API","pages":[{"title":"Introduction","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":"Introduction - Permutive","deploymentId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","buildId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","dynamics":[],"chunks":[]}