Discovers cohorts you have not specified whose users correlate with a seed audience — the cohorts most worth considering as an extension of it, each with its overlap and index (affinity). A discovery tool, not a reporting one.
Example prompt
Which cohorts should I add to my luxury car intenders audience to extend its reach, and how many net-new users would each bring?
Parameters
enum[]
Restrict the suggestions to these cohort types. Omit to suggest all types the caller can see except lookalikes. min 1 item. each one of: custom, lookalike, contextual, standard, classificationModel, advertiser, curated.
string[]
Cohort short ids to exclude from the suggestions, on top of the seed’s own cohorts (always excluded).
boolean
Include low confidence suggestions. Defaults to true.
number (double)
Drop suggestions containing at least this share of the seed (0 to 1). Defaults to 0.9.
integer (int64)
Only suggest cohorts with at least this many users. Defaults to 1000.
enum
How to trade estimate precision against how long the call takes. Defaults to balanced. one of: accuracy, balanced, speed.
string
Opaque token from a previous response’s next_page_token, to fetch the next page.
RestrictTo object
Narrow the measured 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.
string
The seed audience to extend, a LISP S-expression over cohort short ids. Required unless you are paging.
Window object
The date window to measure 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 the suggestions are drawn from and measured across. min 1 item.
Returns
string
Pass as page_token to fetch the next page of suggestions. Absent on the last page. Valid for about 15 minutes from the first page, so other tool calls in between are fine.
CohortReach object
The seed audience’s own reach over the window, with any restrict_to applied. Returned on the first page only.
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.
AudienceExtension[]
A page of up to 50 suggested cohorts to extend the seed audience, ordered by index descending (strongest affinity first). Near-duplicates of the seed (overlap at or above max_overlap) are excluded, so a high-index cohort that merely re-surfaces the seed doesn’t crowd out genuine extensions.
Show AudienceExtension
string[]
required
Which of the requested workspaces this cohort can be used from. Pass any of these to follow-up tools. min 1 item.
string
required
Short cohort identifier. Pass to get_cohort_detail, and as the cohort reference in measure_audiences expressions.
enum
required
Cohort type one of: custom, lookalike, contextual, standard, classificationModel, advertiser, curated.
enum
required
How reliable this suggestion’s index and overlap are — they’re estimated from sampled sketches, not exact counts, and the estimate is noisiest when the overlap with the seed is small. Treat high as trustworthy; on medium and low, weigh that the true value may differ substantially, and re-measure with compare_audience before reporting a figure. All three levels are returned by default; set include_low_confidence to false to drop low. one of: high, medium, low.
string (date-time)
When the cohort was created (ISO-8601). Absent for cohort types that don’t record a creation time (e.g. standard cohorts).
number (double)
required
Those net-new users as a percentage of the seed’s own size: incremental_reach_users / seed_reach.users × 100 — how much adding this cohort would grow the seed audience.
integer (int64)
required
Net-new users this cohort would add to the seed — users in the cohort but not already in the seed.
number (double)
required
How much more or less likely a cohort member is to be in this cohort than the average user: 1.0 = average, above 1.0 = over-represented.
string
required
Human-readable cohort name.
number (double)
required
What percentage of the seed audience is also in this cohort: overlap_users / seed_reach.users × 100.
integer (int64)
required
Users the cohort shares with the seed audience.
string (uuid)
Workspace where this cohort was originally defined.
string
required
Whether the cohort is enabled or disabled.
enum
required
What the cohort targets: a user, a group of users (ie. a household), or a piece of content. one of: user, user_group, content.
string[]
Tags applied to the cohort. Empty when the cohort has none.
integer (int64)
required
The cohort’s own size over the window.
integer (int32)
required
How many suggestions this query returns in total, across all pages — at most 200, the strongest by index.
string[]
Seed cohorts not available in any of the requested workspaces. Returned on the first page only.
WeakSeed object
Present only when no cohort in the library was a usable extension of the seed — the seed overlaps too little to extend from. Returned on the first page only.
Show WeakSeed
string
required
Why the seed is considered weak.
integer (int32)
required
The number of suggestions found (0 when the seed is too weak to extend from).
Assistant
Responses are generated using AI and may contain mistakes.