Measures how a set of cohorts you specify relate to an audience: for each cohort, its overlap with the audience, its index — how much more or less likely a cohort member is to be in it than the average user — and how many net-new users it would add. Use this to get precise numbers on how cohorts are related to each other.
Example prompt
Which of my sports cohorts over-index against my luxury car intenders audience, and by how much?
Parameters
string
required
The audience to compare against, a LISP S-expression over cohort short ids.
string[]
required
The cohorts to compare the audience against — their short ids. min 1 item.
enum
How to trade estimate precision against how long the call takes. Omit for accuracy, which is the right choice here: this tool exists to produce figures you can report. one of: accuracy, balanced, speed.
RestrictTo object
Narrow the compared population to activity matching these dimensions.
Show RestrictTo
string[]
ISO 3166-1 alpha-3 country codes (e.g. GBR, USA). When set, only activity in these countries is counted. Use get_workspace_details to find which workspaces have user activities in which countries.
string[]
Domain names (e.g. example.co.uk). When set, only activity on these domains is counted. Use the workspace’s own domains, from get_workspace_details.
Window object
The date window to compare over.
Show Window
string (date)
End of the window (inclusive), ISO date e.g. 2026-06-30. Omit to default to today.
string (date)
Start of the window (inclusive), ISO date e.g. 2026-06-01. Omit to default to 30 days before end.
string[]
required
Workspaces whose user-behaviour data is compared across. min 1 item.
Returns
CohortReach object
required
The audience’s own reach over the window, with any restrict_to applied — the denominator behind every comparison’s overlap_percent and incremental_reach_percent.
Show CohortReach
integer (int64)
required
Estimated page views over the measurement window.
integer (int64)
required
Estimated unique users over the measurement window.
integer (int64)
required
Estimated video views over the measurement window.
AudienceComparison[]
One entry per comparison cohort available in the requested workspaces, in the order you supplied them.
Show AudienceComparison
string
required
The comparison cohort’s short id.
number (double)
required
Those net-new users as a percentage of the audience’s own size: incremental_reach_users / audience_reach.users × 100 — how much adding this cohort would grow the audience.
integer (int64)
required
Net-new users this cohort would add to the audience — users in the cohort but not already in it.
number (double)
required
How much more or less likely an audience member is to be in this cohort than the average user: 1.0 = average, 1.5 = 1.5× more likely, below 1.0 = under-represented.
number (double)
required
What percentage of the audience is also in this cohort: overlap_users / audience_reach.users × 100.
integer (int64)
required
Users the cohort shares with the audience.
integer (int64)
required
The cohort’s own size over the window.
string[]
Comparison cohorts (or cohorts referenced by the audience) not available in any of the requested workspaces.
{"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/mcp/compare_audience","slug":"/api/mcp/compare_audience","pageMetadata":{"title":"Compare Audience","description":null,"href":"/api/mcp/compare_audience"},"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={blockquote:`blockquote`,code:`code`,p:`p`,strong:`strong`,..._provideComponents(),...props.components},{Expandable,Heading,Info,ParamField,ResponseField}=_components;if(!Expandable)_missingMdxReference(`Expandable`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Info)_missingMdxReference(`Info`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!ResponseField)_missingMdxReference(`ResponseField`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Tool name`}),` `,_jsx(_components.code,{children:`compare_audience`})]}),`\n`,_jsx(Info,{children:`Read-only · Idempotent`}),`\n`,_jsx(_components.p,{children:`Measures how a set of cohorts you specify relate to an audience: for each cohort, its overlap with the audience, its index — how much more or less likely a cohort member is to be in it than the average user — and how many net-new users it would add. Use this to get precise numbers on how cohorts are related to each other.`}),`\n`,_jsx(Heading,{level:`2`,id:`example-prompt`,children:`Example prompt`}),`\n`,_jsxs(_components.blockquote,{children:[`\n`,_jsx(_components.p,{children:`Which of my sports cohorts over-index against my luxury car intenders audience, and by how much?`}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`parameters`,children:`Parameters`}),`\n`,_jsx(ParamField,{body:`audience`,type:`string`,required:true,id:`param-audience`,children:_jsx(_components.p,{children:`The audience to compare against, a LISP S-expression over cohort short ids.`})}),`\n`,_jsx(ParamField,{body:`comparison_cohorts`,type:`string[]`,required:true,id:`param-comparison-cohorts`,children:_jsx(_components.p,{children:`The cohorts to compare the audience against — their short ids. min 1 item.`})}),`\n`,_jsx(ParamField,{body:`optimise_for`,type:`enum`,id:`param-optimise-for`,children:_jsxs(_components.p,{children:[`How to trade estimate precision against how long the call takes. Omit for `,_jsx(_components.code,{children:`accuracy`}),`, which is the right choice here: this tool exists to produce figures you can report. one of: `,_jsx(_components.code,{children:`accuracy`}),`, `,_jsx(_components.code,{children:`balanced`}),`, `,_jsx(_components.code,{children:`speed`}),`.`]})}),`\n`,_jsxs(ParamField,{body:`restrict_to`,type:`RestrictTo object`,id:`param-restrict-to`,children:[_jsx(_components.p,{children:`Narrow the compared population to activity matching these dimensions.`}),_jsxs(Expandable,{title:`RestrictTo`,children:[_jsx(ParamField,{body:`countries`,type:`string[]`,id:`param-countries`,children:_jsx(_components.p,{children:`ISO 3166-1 alpha-3 country codes (e.g. GBR, USA). When set, only activity in these countries is counted. Use get_workspace_details to find which workspaces have user activities in which countries.`})}),_jsx(ParamField,{body:`domains`,type:`string[]`,id:`param-domains`,children:_jsx(_components.p,{children:`Domain names (e.g. example.co.uk). When set, only activity on these domains is counted. Use the workspace’s own domains, from get_workspace_details.`})})]})]}),`\n`,_jsxs(ParamField,{body:`window`,type:`Window object`,id:`param-window`,children:[_jsx(_components.p,{children:`The date window to compare over.`}),_jsxs(Expandable,{title:`Window`,children:[_jsx(ParamField,{body:`end`,type:`string (date)`,id:`param-end`,children:_jsx(_components.p,{children:`End of the window (inclusive), ISO date e.g. 2026-06-30. Omit to default to today.`})}),_jsx(ParamField,{body:`start`,type:`string (date)`,id:`param-start`,children:_jsx(_components.p,{children:`Start of the window (inclusive), ISO date e.g. 2026-06-01. Omit to default to 30 days before end.`})})]})]}),`\n`,_jsx(ParamField,{body:`workspace_ids`,type:`string[]`,required:true,id:`param-workspace-ids`,children:_jsx(_components.p,{children:`Workspaces whose user-behaviour data is compared across. min 1 item.`})}),`\n`,_jsx(Heading,{level:`2`,id:`returns`,children:`Returns`}),`\n`,_jsxs(ResponseField,{name:`audience_reach`,type:`CohortReach object`,required:true,id:`param-audience-reach`,children:[_jsxs(_components.p,{children:[`The audience’s own reach over the window, with any restrict_to applied — the denominator behind every comparison’s `,_jsx(_components.code,{children:`overlap_percent`}),` and `,_jsx(_components.code,{children:`incremental_reach_percent`}),`.`]}),_jsxs(Expandable,{title:`CohortReach`,children:[_jsx(ResponseField,{name:`page_views`,type:`integer (int64)`,required:true,id:`param-page-views`,children:_jsx(_components.p,{children:`Estimated page views over the measurement window.`})}),_jsx(ResponseField,{name:`users`,type:`integer (int64)`,required:true,id:`param-users`,children:_jsx(_components.p,{children:`Estimated unique users over the measurement window.`})}),_jsx(ResponseField,{name:`video_views`,type:`integer (int64)`,required:true,id:`param-video-views`,children:_jsx(_components.p,{children:`Estimated video views over the measurement window.`})})]})]}),`\n`,_jsxs(ResponseField,{name:`comparisons`,type:`AudienceComparison[]`,id:`param-comparisons`,children:[_jsx(_components.p,{children:`One entry per comparison cohort available in the requested workspaces, in the order you supplied them.`}),_jsxs(Expandable,{title:`AudienceComparison`,children:[_jsx(ResponseField,{name:`cohort_id`,type:`string`,required:true,id:`param-cohort-id`,children:_jsx(_components.p,{children:`The comparison cohort’s short id.`})}),_jsx(ResponseField,{name:`incremental_reach_percent`,type:`number (double)`,required:true,id:`param-incremental-reach-percent`,children:_jsxs(_components.p,{children:[`Those net-new users as a percentage of the audience’s own size: `,_jsx(_components.code,{children:`incremental_reach_users`}),` / `,_jsx(_components.code,{children:`audience_reach.users`}),` × 100 — how much adding this cohort would grow the audience.`]})}),_jsx(ResponseField,{name:`incremental_reach_users`,type:`integer (int64)`,required:true,id:`param-incremental-reach-users`,children:_jsx(_components.p,{children:`Net-new users this cohort would add to the audience — users in the cohort but not already in it.`})}),_jsx(ResponseField,{name:`index`,type:`number (double)`,required:true,id:`param-index`,children:_jsx(_components.p,{children:`How much more or less likely an audience member is to be in this cohort than the average user: 1.0 = average, 1.5 = 1.5× more likely, below 1.0 = under-represented.`})}),_jsx(ResponseField,{name:`overlap_percent`,type:`number (double)`,required:true,id:`param-overlap-percent`,children:_jsxs(_components.p,{children:[`What percentage of the `,_jsx(_components.strong,{children:`audience`}),` is also in this cohort: `,_jsx(_components.code,{children:`overlap_users`}),` / `,_jsx(_components.code,{children:`audience_reach.users`}),` × 100.`]})}),_jsx(ResponseField,{name:`overlap_users`,type:`integer (int64)`,required:true,id:`param-overlap-users`,children:_jsx(_components.p,{children:`Users the cohort shares with the audience.`})}),_jsx(ResponseField,{name:`users`,type:`integer (int64)`,required:true,id:`param-users-1`,children:_jsx(_components.p,{children:`The cohort’s own size over the window.`})})]})]}),`\n`,_jsx(ResponseField,{name:`unavailable`,type:`string[]`,id:`param-unavailable`,children:_jsx(_components.p,{children:`Comparison cohorts (or cohorts referenced by the audience) not available in any of the requested workspaces.`})})]})}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":"Compare Audience","description":null,"href":"/api/mcp/compare_audience"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Example prompt","slug":"example-prompt","depth":2,"children":[]},{"title":"Parameters","slug":"parameters","depth":2,"children":[]},{"title":"Returns","slug":"returns","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/permutive/9a9f86ed1fb0eb1f/agent-chat-rail.js"],"subdomain":"permutive","siteName":"Permutive","title":"Compare Audience - Permutive","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-17T10:23:16.372Z","originalFileLocation":"api/mcp/compare_audience.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=\"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=\"Compare Audience - Permutive\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Permutive\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.permutive.com/api/mcp/compare_audience\">\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=Audience+Analysis\u0026amp;title=Compare+Audience\u0026amp;theme=476d64e99ccc72d9df9ea1e6\u0026amp;signature=d6944ad7ba451b05bd2263fe0019251d1e5d944c18e5497ee335ef7eabaff451\">\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=\"Compare Audience - Permutive\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://permutive.mintlify.site/_mintlify/api/og/v2?division=Audience+Analysis\u0026amp;title=Compare+Audience\u0026amp;theme=476d64e99ccc72d9df9ea1e6\u0026amp;signature=d6944ad7ba451b05bd2263fe0019251d1e5d944c18e5497ee335ef7eabaff451\">\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/mcp/compare_audience\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api/mcp/compare_audience.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/mcp/compare_audience#webpage\",\"url\":\"https://docs.permutive.com/api/mcp/compare_audience\",\"name\":\"Compare Audience\",\"dateModified\":\"2026-11-17T10:23:16.372Z\",\"isPartOf\":{\"@id\":\"https://docs.permutive.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.permutive.com/api/mcp/compare_audience#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.permutive.com/api/mcp/compare_audience#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Tool Reference\",\"item\":\"https://docs.permutive.com/api/mcp/tools\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Compare Audience\",\"item\":\"https://docs.permutive.com/api/mcp/compare_audience\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.permutive.com/api/mcp/compare_audience#article\",\"headline\":\"Compare Audience\",\"name\":\"Compare Audience\",\"url\":\"https://docs.permutive.com/api/mcp/compare_audience\",\"mainEntityOfPage\":{\"@id\":\"https://docs.permutive.com/api/mcp/compare_audience#webpage\"},\"dateModified\":\"2026-11-17T10:23:16.372Z\",\"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/mcp/compare_audience.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","pages":[{"title":"APIs","href":"/api/introduction"}]},{"tab":"MCP","groups":[{"group":"MCP Server","pages":[{"title":"Introduction","href":"/api/mcp/introduction"},{"group":"Releases","pages":[{"title":"1.1 - Campaign Optimization","href":"/api/mcp/releases/v1-1"},{"title":"1.2 - Audience Extension, Comparison \u0026 Detailed Analysis","href":"/api/mcp/releases/v1-2"},{"title":"1.3 - Usage Credits","href":"/api/mcp/releases/v1-3"}]}]},{"group":"Use cases","pages":[{"title":"Use cases","sidebarTitle":"Overview","href":"/api/mcp/use-cases/overview"},{"group":"Pitching and planning","pages":[{"title":"Planning a custom audience for a campaign brief","href":"/api/mcp/use-cases/planning-an-audience"},{"title":"Building audiences from an RFP","href":"/api/mcp/use-cases/building-audiences-from-an-rfp"}]},{"group":"Delivering campaigns","pages":[{"title":"Optimizing a campaign in flight","href":"/api/mcp/use-cases/optimizing-a-campaign-in-flight"},{"title":"Reporting on a finished campaign","href":"/api/mcp/use-cases/reporting-on-a-finished-campaign"}]}]},{"group":"Tool Reference","pages":[{"title":"Overview","href":"/api/mcp/tools"},{"group":"Workspaces","pages":[{"title":"Get Organizations And Workspaces","href":"/api/mcp/get_orgs_and_workspaces"},{"title":"Get Workspace Details","href":"/api/mcp/get_workspace_details"}]},{"group":"Campaigns","pages":[{"title":"Get Campaign","href":"/api/mcp/get_campaign"},{"title":"List Campaigns","href":"/api/mcp/list_campaigns"}]},{"group":"Cohorts","pages":[{"title":"Get Cohort Detail","href":"/api/mcp/get_cohort_detail"},{"title":"List Cohorts","href":"/api/mcp/list_cohorts"},{"title":"Search Cohorts","description":null,"href":"/api/mcp/search_cohorts"}]},{"group":"Audience Analysis","pages":[{"title":"Compare Audience","href":"/api/mcp/compare_audience"},{"title":"Find Audience Extensions","description":null,"href":"/api/mcp/find_audience_extensions"},{"title":"Measure Audiences","href":"/api/mcp/measure_audiences"}]}]}]}]},"basePath":"","title":"Compare Audience - Permutive","deploymentId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","buildId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","dynamics":[],"chunks":[]}