YPulse Insights

Direct structured query against YPulse's behavioral and omnibus survey database. Returns weighted response distributions for specific survey questions, with optional demographic filtering and breakdowns. Prefer this over behavior_tracker for exact percentages or a demographic cut on a known question. Provide either question_ids, or topics and/or search to resolve matching questions server-side (mutually exclusive). Discovery mode resolves and returns distributions for up to limit matches (default 10, max 100); page further matches with offset (advance by limit when match_total > offset + limit). Use behavior_question_list when you need the full inventory without distributions. For high-cardinality filter_by values (household income, DMA) whose full lists are not in the tool description, call behavior_distinct_data first. Question IDs are NOT globally unique — the same ID (e.g. S110, T220, A100) is reused across topics and survey waves. A question_id is unique only within a survey_source_id. This tool returns one separate results[] block per distinct question context (question_text + question_topic + survey_type + survey_source_id). Pin a wave with filter_by.survey_source_id (e.g. NA_BEHAVIORAL_202101B), or pass survey_type / question_topic / question_text on the question_ids path. When multiple texts still share the same question_id and survey_source_id after filters (rare data collision), context_collisions lists the colliding question texts. Cross-source reuse of the same literal ID is expected and is not a collision — use survey_source_id to disambiguate. Response shape: results[] blocks with question_id, question_text, question_topic, survey_type, survey_source_id, question_type, optional statement (row label for Matrix/MR sub-items), base_group, base, total_weighted_respondents, and responses[] entries of {response_option, weighted_pct, weighted_count}; plus match_total and context_collisions (discovery also echoes limit and offset). base_group and base describe who was asked the question (the survey's own base population), not any filter_by you applied; the top-level applied_filters object echoes the filter_by values in effect, so the data is scoped to that subset even though base is unchanged. Matrix sub-items: response_option is the Likert/scale label; statement is the row statement. Multiple Response check-all batteries: response_option is Selected, Not selected, or Not in base; statement is the reason label. Not in base is battery-level skip logic — the same share across all sub-items in a check-all bank is expected; Selected and Not selected vary per reason. questions_not_found lists IDs absent from the database; an empty results array with no questions_not_found entry means the ID exists but has no rows in the applied time window (try a wider months_lookback or calendar fielding range). Skip/non-response methodology codes (-77 skip-logic coded, -66 skip-logic open end, 0 saw but did not answer) and null/blank answers are excluded from responses[] and the weighted denominator; Multiple Response Not in base is retained (battery-level skip, different semantics). Open End, String, and Mean questions return at most the top 100 responses by weighted_count; when more exist the block sets responses_truncated, responses_total_count (full distinct-answer count), and responses_limit. weighted_pct for those types still uses the full-answer denominator.

behavior_data

Returns paginated DISTINCT values for one to three filterable behavioral survey demographic columns (especially high-cardinality ones such as household income or DMA). Use before behavior_data filter_by when exact labels are unknown — column names themselves are listed on behavior_data's filter_by description. Optional search narrows stringified values. NULLs are excluded. For household income, methodology non-response codes (0, -66, -77) are excluded so values are usable as real incomes; integer columns return plain ints. High-cardinality columns (esp. household income) may need many pages at the default limit of 100 — use total_count with limit/offset. Scoped by months_lookback (default 24) and permission-clamped to the token's DATA_BEHAVE regions.

behavior_distinct_data

Directly answers what YPulse surveys or asks about a subject, and which survey questions or topics exist on it. Returns the inventory of matching survey questions with their text, topic, type, base group, fielding history keyed by survey_source_id (waves[] / wave_count / survey_source_ids), and the survey years they cover. Use it both as a direct answer when someone wants to know what YPulse measures on a subject, and as the discovery step to find question IDs and survey_source_id values before calling behavior_data. Question IDs are NOT globally unique — pin a wave with survey_source_id from waves[] / survey_source_ids when calling behavior_data.

behavior_question_list

Quantitative survey data from YPulse's Behavioral and Trend database. Returns response percentages with demographic and regional breakdowns, plus interactive dashboard URLs for further exploration on YPulse.com. Use this as the primary tool when the question is about what young consumers do, think, or feel. Prefer behavior_data for exact percentages on a known question ID; use this for open-ended questions or when the question ID is unknown. Pair with content_search when cultural context behind the behavior is needed. When presenting results to the user, always cite each entry from the response's sources list as a markdown link, [Title](url) — never a bare title, and never wait for the user to ask for sources.

behavior_tracker

Direct structured query against YPulse's Brand Tracker database, returning precise awareness, mindshare, purchase intent, YScore, and YScore diagnostic metrics for 1,200+ brands among 13-39-year-olds in North America and Western Europe. Prefer this over brand_tracker for exact figures, a demographic cut, or a ranked YScore leaderboard; omit brands for a top-10 YScore ranking by region. When the user has not specified an exact brand name, call brand_list_data first to discover valid names. For high-cardinality filter_by values (household income, DMA, zip, postal code) whose full lists are not in the tool description, call brand_distinct_data first.

brand_data

Returns paginated DISTINCT values for one to three filterable Brand Tracker demographic columns (especially high-cardinality ones such as household income, DMA, US zip code, or Canadian postal code). Use before brand_data filter_by when exact labels are unknown — column names themselves are listed on brand_data's filter_by description. Optional search narrows stringified values (useful for zip/postal). NULLs are excluded. For household income, methodology non-response codes (0, -66, -77) are excluded so values are usable as real incomes; integer columns return plain ints. High-cardinality columns (esp. household income, tens of thousands of distinct values) may need many pages at the default limit of 100 — use total_count with limit/offset. Permission-clamped to the token's DATA_BRAND regions.

brand_distinct_data

Lists all brands tracked in the YPulse brand database, limited to the regions the user has access to. Returns each brand's name, the regions it appears in, and its industry or industries. Use this tool to discover available brand names before calling brand_data — especially for open-ended queries like "what footwear brands does YPulse track?" or when the user has not specified an exact brand name. Filter by region or industry to narrow results. Paginated: the response returns one page of brands with total_count (the full match count) plus the applied limit and offset; page through large regions with limit and offset.

brand_list_data

Quantitative brand performance metrics from YPulse's Brand Tracker. Returns awareness, purchase intent, YScore, all 20 diagnostic scores, key driver analysis, and demographic breakdowns for 1,200+ brands among 13-39-year-olds in North America and Western Europe. Use this as the primary tool for brand metrics and rankings. Prefer brand_data for exact figures or a specific metric_type; use this for open-ended or key-driver questions. Pair with content_search when the question asks how young people perceive or feel about a brand. When the response includes a sources list, always cite each entry as a markdown link, [Title](url) — never a bare title, and never wait for the user to ask for sources.

brand_tracker

Semantic search over YPulse's published articles, reports, webinars, and newsfeeds. Returns excerpts with titles, publication dates, permalinks, and WordPress post_id values. Pass exclude_post_ids to omit posts already shown in a prior call — useful when surfacing related content without repeating the same top hits. Use this as the primary tool when the user asks for YPulse's own published material. Use alongside brand_tracker or behavior_tracker when the question asks why or what the cultural context is behind a metric. When presenting results to the user, always cite each document from the response's sources list as a markdown link, [Title](url) — never a bare title, and never wait for the user to ask for sources.

content_search