find_media
ChatGPTSearches for media entities (sites/apps) by name. Intended for questions like "what sites match X" or "find the ID for Y". get_metric, get_trend, get_demographics, get_audience_overlap, and get_cross_visiting resolve media internally and do not require a prior find_media call. This is a prefix search — query="Nexstar" returns all Nexstar entities in one call. Args: query: Site, app, or brand as the user names it (e.g. "HBO", "cnn.com"), passed verbatim; a brand is not equivalent to its domain. The shortest parent name returns the full portfolio. geo: Geographic market, default "US". product: Product slug for context, default "mmx". report: Report slug for context, default "keymeasures". time_period: Numeric period code. Defaults to last published month. exact_match: Require exact name match, default False.
get_audience_overlap
ChatGPTAudience overlap (duplication) across 2–10 sites/apps — the shared audience and what fraction of each entity's audience also visits the others. For MMX, platform="multiplatform" (the default) returns the combined Desktop-and-Mobile figure plus the Desktop AND Mobile breakdowns together under each entity's "by_platform" key — a single call covers all three; separate desktop and mobile calls return data already present in the multiplatform response. The combined figure is the Desktop+Mobile dedup; it is not Total Digital Population, which also includes Social and is not reported here. Reports a per-entity value for every requested metric plus the duplicated audience ("2 or More Sites" and "All Sites") and the combined unduplicated total. Supports an audience filter (age/gender/HH-size etc.) and US local markets (CS Markets). Args: media: 2–10 entities as the user names them (e.g. ["HBO", "ESPN", "cnn.com"]), each passed verbatim; a brand is not equivalent to its domain. metrics: Metrics to report, e.g. ["unique visitors", "reach", "minutes", "average minutes per visitor"]. Defaults to unique visitors + % reach. (mmx only; video/mobile products report unique visitors.) audience: Optional audience filter. Pass a single string ("women 25-54", "adults 18+", "HH Size: 1") for a standard filter, OR a list of strings to combine multiple segments as an Advanced Audience (e.g. ["HH Size: 1", "HH Size: 2", "HH Size: 3"]). Multiple segments are OR-combined into one request (targetType=1). Omit for total. time: "last_month" (default), "YYYY-MM", or raw period integer. geo: "US" (default), a country, or a US local market / CS Market (e.g. "Boston, MA"). CS Markets run on the MMX Desktop data source only (no Mobile or combined breakdown), and are available for the mmx product only. product: "mmx" (default), "video" (VMX), "mobile". platform: "multiplatform" (default) — use this for all MMX requests. Returns combined Desktop and Mobile + Desktop + Mobile in one call. "desktop" or "mobile" only when the user explicitly requests a single platform view with no breakdown needed. Ignored for video/mobile products.
get_cross_visiting
ChatGPTOther sites that a site's audience also visits (affinity / cross-visiting). Returns, per co-visited site/category, the shared audience and the requested cross-visiting metrics. Args: media: Base site/app/brand as the user names it, passed verbatim. For multiple base entities pass a list or a semicolon-joined string ("PayPal;CNN.COM"). time: "last_month" (default), "YYYY-MM", or raw period integer. geo: Geographic market, default "US" (e.g. "Brazil" for non-US). product: "mmx" (default), "video" (VMX), "mobile". platform: "multiplatform" (default), "desktop", "mobile". Ignored for video/mobile. limit: Co-visited sites to return, default 100. target_category: Target entity category whose members become the rows — an industry ("Automotive", "News") or a rollup ("Top 100 Properties", default). Mutually exclusive with target_entities. target_entities: Specific target entities to use as rows (Digital Entities mode), e.g. ["CNN Brasil", "CNNBRASIL.COM.BR"]. List or semicolon-joined string. When set, only these entities are returned (overrides target_category). metrics: Cross-visiting metrics, e.g. ["Shared Audience (000)", "% Vertical", "% Horizontal", "Index"]. List or semicolon-joined string. Defaults to all four. audience: Audience filter. Single string ("Total Audience", "Males 21+") for a standard target, or a list to combine segments as an Advanced Audience (targetType=1), e.g. ["Females 45+", "Females 35-44"]. Omit for Total Audience. domains_only: When True, expand categories to individual domains (leaf entities) rather than brand/property rollups. Maps to the report's "domains only" option. Works with industry verticals ("Automotive") and the expandable entity sets, but NOT with the "Top N Properties" rollups — those are property-level only. For ranked domain-level rows use target_category="Top 2000 Web Domains" with domains_only=False.
get_demographics
ChatGPTFull demographic breakdown for a site — Demographic Profile, Demographic Breakouts, and any widget asking for age/gender/region/income breakdown of an entity's audience. Returns all segments in a single call. A request that names "Total Digital Population" or "TDP" must be sent with platform="total_digital_population". platform="multiplatform" is Desktop+Mobile only and answering a TDP question with it reports the wrong audience under the user's own words for a different one (CF-3510). Args: media: Site, app, or brand as the user names it, passed verbatim; a brand is not equivalent to its domain. For multiple entities pass comma-separated names, e.g. "Yahoo,Yahoo Sports". time: "last_month" (default), "YYYY-MM", or raw period integer. geo: Geographic market, default "US". product: "mmx" (default), "video" (VMX), "mobile". platform: "multiplatform" (default), "desktop", "total_digital_population", "mobile". Ignored for video/mobile. "multiplatform" is the Desktop+Mobile dedup, reported under the "Desktop and Mobile" by_platform key — not Total Digital Population. "total_digital_population" is the Desktop+Mobile dedup plus Social, a substantially larger number; use it whenever the user asks for Total Digital Population or TDP by name. Report each figure under the platform name the response gives it (CF-3510). audience: Comma-separated demographic dimensions to break down by (e.g. "Children,HH Size", "Region,Language", "Persons"). Default: age/gender breakdown. Valid segments: standard age/gender targets, plus "Children", "HH Size", "HHI" (household income), "Race", "Region", "Language". Prefix with "advanced," for a filtered single segment (e.g. "advanced,Children: Yes"). metrics: List of metrics to return alongside UV (e.g. ["% Reach", "% Composition", "Total Visits", "Total Views"]). Default: unique visitors only. For multiplatform, % Reach breakdown by Desktop/Mobile is always included. audience_universe: Audience universe for multiplatform MMX, same values as get_metric (e.g. "Desktop 2+ and Total Mobile 18+", "Desktop 2+ and Total Mobile 13+"). Defaults to "Desktop 2+ and Total Mobile 18+" (universeTypeId 4), which the demographicprofile report requires to return data for multiplatform/mobile. Reporting the result: product + report name the Comscore product and report that answered ("Comscore MMX®" + "Demographic Profile"); state them when asked where the figures came from, and do not name a report that was not used. wider_platform_available, when present, names a broader platform the same metric is also published for — mention it rather than presenting the returned platform as the only reading of the request, and do not silently substitute it.
get_entity_status
ChatGPTEntity Status widget — shows measurement coverage for a site/publisher across platforms (Desktop, Smartphone iOS/Android, CTV) and content types (Display, Video). Use for the Entity Status widget or when the user asks about measurement/tagging status. Args: media: Site, category, or brand (e.g. "CNN.COM", "Social", "ESPN.com Sites"). time: "last_month" (default), "YYYY-MM", or raw period integer. geo: Geographic market, default "US". entity_type: "Digital Entities" (default) for a specific site/brand, or "Digital Categories" for a category (e.g. "Social", "News") — a category returns the measurement status of every property within it.
get_metric
ChatGPTSingle-month metric for a site or publisher. Accepts a media name directly; a prior lookup is not required. Scope notes: - A request that names "Total Digital Population" or "TDP" must be sent with platform="total_digital_population". platform="multiplatform" is Desktop+Mobile only and answering a TDP question with it reports the wrong audience under the user's own words for a different one (CF-3510). - Covers a single month. Multiple months ("last 6 months", a date range) are the domain of get_trend. - Returns a single segment via target=. A full age/gender breakdown is the domain of get_demographics. - Covers named entities. A ranked list of sites in a category (Media Ranker, Industry Ranker) is the domain of get_top_entities. When specific named entities are given (e.g. "OUTKICK.COM;PayPal"), each is queried here individually — or, to compare several sites and/or metrics, pass them all as lists to get_trend in one call (a one-month time_range like "2026-08:2026-08" gives the single month). - Handles standard age/gender demo labels via target=. Lifestyle/behavioral/psychographic audiences (e.g. "married", "EV buyer", "gamer") are the domain of get_plan_metrix. - Sub-properties or channels (e.g. "CNN by section") are returned via expand_all_media=True. - Company properties (e.g. "Microsoft properties", "Google sites") use media="Microsoft" with expand_all_media=True. Comscore has a parent/child media tree; the publisher is the parent and its sites/apps are children, so individual domains need not be enumerated. Args: media: Site, app, or brand as the user names it (e.g. "HBO", "cnn.com"), passed verbatim, including any qualifier in parentheses (e.g. "ESPN (Mobile App)", "CNN (TV App)"). Qualifiers are significant and a brand is not equivalent to its domain. metric: "unique visitors", "reach", "minutes", "pages", "page views (mm)", "visits", "frequency", "viewers", "video views", "composition index", "% composition", "composition index videos", "composition index minutes", "% composition minutes", "avg daily visitors", "desktop-only uv", "mobile-only uv" (multiplatform mmx only — exclusive audiences), (and aliases like "people", "UV", "time spent"). "Composition index" / "% composition" express how concentrated the audience is vs. the target's universe — they require target= to be set to be meaningful (mmx only). time: "last_month", "YYYY-MM", or raw period integer. geo: Geographic market, default "US". product: "mmx" (default, web+app), "video" (VMX), "mobile" (Mobile Metrix). platform: For mmx: "desktop" (default), "multiplatform" (desktop+mobile), "total_digital_population", "mobile". mmx "multiplatform" is the Desktop+Mobile dedup — it is NOT Total Digital Population. "total_digital_population" is the widest MMX view: the Desktop+Mobile dedup PLUS Social. It is a substantially larger number — use it whenever the user asks for Total Digital Population or TDP by name. Comscore publishes it for audience size, reach, composition and adult age only. For video: "multiplatform" (default, = Desktop+Mobile+CTV), "desktop", "mobile", "ctv". limit: Max rows, default 10. target: Demographic segment — "gen z", "women", "18-24", "men 25-34", etc. For combined/Advanced Audience (multiple segments OR'd), prefix with "advanced," e.g. "advanced,Males: 65+,Males: 55-64,Females: 65+". These are OR-combined (targetType=1) and returned as a single aggregate value. expand_all_media: True to return sub-property breakdown with hierarchy (depth, parent_id). beta_data: True to use Comscore beta/preview data instead of standard production data (the UI "beta data" toggle). Default False (standard). mmx only. percent_change: True to also fetch the prior month and report the change vs. that period (adds prev_value/prev_value_human/percent_change to output). audience_universe: Audience universe for multiplatform MMX reports. Only applies when platform="multiplatform". Valid values: "Desktop 2+ and Total Mobile 18+" (id=4, default for most markets), "Desktop 2+ and Total Mobile 13+" (id=6), "Desktop 6+ and Total Mobile 18+" (id=4, some geos), "Defau…
get_plan_metrix
ChatGPTPlan Metrix metrics (views, visitors, reach, etc.) for a custom audience segment. Use this tool whenever the audience is anything other than a plain age/gender demo — including: household size, income, education, purchase intent, lifestyle, psychographics, or ANY combination of multiple segments (e.g. Female AND household size 2 or 3). get_metric only accepts a single age/gender target; all other audience definitions require this tool. search_plan_metrix_audience returns the numeric segment IDs this tool requires. When that search returns several segments that each fit the requested audience, ask the user which to use (or whether to OR them) before calling this tool. For demographic breakdown queries (e.g. "show results by Hispanic sub-segment"), media="total internet" is appropriate — the audience segments are the rows, not a media filter. Audience expressions combine all required segments: use ^ (AND) / | (OR) and parentheses to compose a single expression (e.g. "A^(B|C)"). One expression describes ONE audience, so combine the segments that together define it into one expression — never pull its parts separately and add them up, which double-counts anyone in more than one part. To compare or characterise several separate audiences, pass them as a list — see BATCHING. BATCHING: media, metric and audience all accept lists, and one call covers every combination of them — pass all the entities, metrics and audiences you need rather than looping. A list returns a rows table instead of a single flat value: one row per entity, or one row per entity x audience when several audiences are given (each row then carries audience and audience_expr). Characterising an audience across 5-6 segments is one call with audience=["6339", "65076", ...], not one call per segment. time is the exception: Plan Metrix allows only one period per report, so a multi-month trend genuinely needs one call per month. Batch the other two axes into each of those calls (e.g. 6 entities x 2 metrics x 11 months = 11 calls, not 132). CROSSTAB MODE: When the user asks for a matrix of row segments × column segments (e.g. "show Hispanic sub-segments as rows and music purchase categories as columns"), pass: - audience_rows: the row segment expression (e.g. "6607|4827|5965") - audience: the column segment expression (e.g. "859216|859640|859641") - metric: "target audience (000)" and/or "% vertical" — both are returned natively in one call. This uses a single API call instead of N×M separate calls. Args: media: "total internet" for universe figures, a PMX category name (e.g. "Entertainment", "Automotive", "News"), or a specific domain/brand name (e.g. "netflix.com"). This is a name, not a numeric ID. Accepts a list to report many entities in one call (e.g. ["netflix.com", "hulu.com", "espn.com"]). audience: Boolean expression of numeric segment IDs (column segments in crosstab mode). Operators: ^ (AND), | (OR), ! (NOT) and parentheses; ^ binds tighter than |. Parentheses are multiplied out before the request, since the API itself does not accept them. E.g. "583658", "583658^5425", "583658|583655", "583658^!12417", "(7863|7876)^(6346|18430|18431)" (age 18-34 AND income $100k+) Accepts a list of expressions to report several audiences in one call (up to 20), e.g. ["6339", "65076", "6339^65076"]. Each expression is one audience; they are reported side by side, never combined. Crosstab mode takes a single expression. metric: "unique visitors" (default), "reach", "total minutes", "total views", "total pages", "total visits", "avg minutes", "avg visits", "composition index", "composition %", "% vertical" (crosstab only). Accepts a list — every metric is returned by the same report, so asking for several costs no more than asking for one. Note: "total views" and "total pages" both map to the same Plan Metrix measure — the Core UI labels it "Total Views MM". "avg visits" is published per platform only — request it with platform="desktop" or platform="mobile". time: "last_month" (default), "YYYY-MM", or raw period integer. One period per call — the API does not acce…
get_top_entities
ChatGPTRanked list of top entities within a category. Covers Media Ranker, Media Industry Ranker, and any widget that shows a ranked list of sites/publishers within an industry or category. When an entity (e.g. "CNN.COM") is the context for a ranker, that entity's industry category is passed as category and the ranked list is returned (a single-entity value is the domain of get_metric). Common entity → category mappings (search_category resolves an unknown category): CNN.COM, BBC → "News" or "General News" Spotify, Apple Music → "Entertainment - Music" or "Entertainment" ESPN, BBC Sport → "Sports" YouTube, Netflix → "Streaming Video" SHOPIFY.COM → "Retail" Adobe Sites → "Technology" PSG.FR, sports teams → "Sports" NPR.ORG → "News" OUTKICK.COM → "Sports" or "News" Lifestyles / BDG Lifestyles / lifestyle brands → "Lifestyles" Automotive brands → "Automotive" Health/medical → "Health" Travel brands → "Travel" For Mobile Metrix ranker (product="mobile"), pass the same category name — it maps to the correct mobile-specific mediaSet automatically. product='video' (VMX) IS supported — use it for video publisher / streaming queries. product='mobile' (Mobile Metrix) IS supported — use it for mobile audience queries. product='mmx' is the default for general web audience queries. Product routing: - "top video publishers", "streaming", "video views", "viewers" → product='video', metric='video views' - "top mobile apps/sites", "mobile audience" → product='mobile' - everything else → product='mmx' Supported metrics by product (use these alias names): mmx (multiplatform): 'unique visitors', 'reach', 'minutes', 'pages', 'visits', 'video views', 'frequency', 'median age', 'mean age' mmx (desktop only): all above + 'composition index' video (VMX): 'video views', 'viewers' (=unique viewers/reach 000), 'minutes', 'reach', 'frequency', 'videos per viewer' mobile: 'unique visitors', 'reach', 'minutes', 'pages', 'visits', 'frequency', 'median age', 'mean age', 'median income' Args: category: "top 100" for general queries; verticals: "news", "sports", "automotive", "health", "travel", "finance", "technology", "retail", "social media", "streaming video", etc. search_category resolves an unknown category. Subcategories are accepted by their Comscore name, e.g. "Lifestyles - Food", "Entertainment - Music", "e-mail". For Media Industry Ranker: this is the entity's industry category, not the entity itself. Also accepts the exact name of the user's own private MMX Saved Group (product="mmx" only) — a custom list of entities they built and saved in the Comscore web UI. Tried automatically as a fallback when the name doesn't match a known category; ranks that group's own member entities instead of an industry vertical. metric: Metric to rank by, default "unique visitors". For multiplatform metrics specify the platform suffix, e.g. "unique visitors, Desktop and Mobile" or "% Reach, Desktop". time: "last_month" (default), "YYYY-MM", or raw period integer. geo: Geographic market, default "US". product: "mmx" (default), "video" (VMX), or "mobile" (Mobile Metrix). platform: "multiplatform" (default), "desktop", "mobile". For video: also "ctv". limit: Top N to return (default 100, max 100). audience: Optional demographic audience to rank by (product="mmx" only), e.g. "Hispanic", "women 25-54", "adults 18+". Ranks the category's entities by their audience within that demographic. Omit for total audience. A Hispanic audience goes here, not in geo.
get_trend
ChatGPTMulti-month time series for one or more sites and metrics — trends, "last N months", or any date range. Accepts media names directly; a prior lookup is not required. Comparisons go in one call: pass every site and every metric the user is comparing as lists (e.g. media=["redfin.com", "zillow.com"], metric=["unique visitors", "pages", "minutes"]). They are fetched together in a single report — a call per site or per metric is slower and adds nothing. A request that names "Total Digital Population" or "TDP" must be sent with platform="total_digital_population". platform="multiplatform" is Desktop+Mobile only and answering a TDP question with it reports the wrong audience under the user's own words for a different one (CF-3510). Args: media: Site, app, or brand as the user names it, passed verbatim, including any qualifier in parentheses (e.g. "ESPN (Mobile App)", "CNN (TV App)"). Qualifiers are significant and a brand is not equivalent to its domain. A list of up to 25 names compares them side by side. metric: Same vocabulary as get_metric. A list of up to 6 metrics returns a series for each. time_range: "last_3_months" (default), "last_6_months", "last_12_months", or "YYYY-MM:YYYY-MM". geo: Geographic market, default "US". product: "mmx" (default), "video" (VMX), "mobile". platform: For mmx: "desktop" (default), "multiplatform" (desktop+mobile), "total_digital_population", "mobile". mmx "multiplatform" is the Desktop+Mobile dedup, not Total Digital Population. "total_digital_population" is the widest MMX view: the Desktop+Mobile dedup PLUS Social. It is a substantially larger number — use it whenever the user asks for Total Digital Population or TDP by name. Comscore publishes it for audience size, reach, composition and adult age only. For video: "multiplatform" (default, = Desktop+Mobile+CTV), "desktop", "mobile", "ctv". limit: Max rows, default 0 (all months). target: Single demographic segment — same vocabulary as get_metric. audience_universe: Audience universe for multiplatform MMX — same values as get_metric. include_total_internet: True to also return a Total Internet baseline series (total_internet_series), at no extra request. expand_all_media: True to return sub-property trend breakdown (e.g. CNN sections over time). One entity and one metric only. A report submission error from this tool indicates an invalid parameter combination. Several sites or metrics: the result carries entities — one object per site with its disclosure fields (requested, entity, entity_id, entity_type, entity_alternatives) and a metrics list, one {metric, platform, coverage, series} per metric. total_internet holds the baseline series per metric when asked for. errors lists any site or metric that could not be reported; the rest are still returned, so report those figures and name what failed. Reporting the result: entity/entity_id/entity_type name the entity the series came from, entity_alternatives lists other entities that matched the request, and universe states the population an unfiltered report covers — same contract as get_metric. State the entity with the figures and read methodology off universe. product + report name the Comscore product and report that answered; state them when asked where the figures came from. wider_platform_available, when present, names a broader platform the same metric is also published for — offer it rather than presenting the returned platform as the only reading of the request.
list_metrics
ChatGPTList all metrics available for a given product and platform by querying the API live. Returns the authoritative metric list for questions like "what metrics are available", "what can I measure", or "what views/reach/minutes metrics exist" for a given data source. Args: product: "mmx" (default, desktop+mobile web), "video" (VMX), "mobile" (Mobile Metrix). platform: "multiplatform" (default), "desktop", "mobile". For mmx: "multiplatform" = dataSource=25, "desktop" = dataSource=1. geo: Geographic market, default "US".
search_category
ChatGPTFind available category names for get_top_entities. Searches Comscore's full US Ranked Categories list, including subcategories such as "Lifestyles - Food" or "e-mail". Args: query: Partial name to search (case-insensitive), e.g. "auto", "health".
search_plan_metrix_audience
ChatGPTSearch the audience segment catalog (~5700 segments) across every data layer get_plan_metrix can target. Returns the numeric segment IDs that get_plan_metrix accepts as input. The catalog spans several data layers, and each match says which layer it came from: - "Plan Metrix" — the survey itself (claimed purchases, ownership, activities, attitudes). - "IAB Digital Interests 2.0" — behavioural interest signals from measured browsing, organised on the IAB content taxonomy (e.g. Business and Finance > Venture Capital, Movies > Horror Movies). - "Demos" / "Demos - Hispanic" — age, gender, income, household size, race breakouts. Segments from different layers combine freely in one get_plan_metrix audience expression, so a definition can mix a survey answer with an IAB interest signal. Which layer a segment belongs to changes what it measures — an IAB interest is browsing behaviour, a Plan Metrix segment is a survey response — so state the layer alongside any number derived from it. Choosing segments — ask before pulling data: - If exactly one match fits the audience the user described, use it directly. - If two or more matches each fit it (e.g. "VP/C-suite" matches both Work Demos > Title > Executive (C-Level) and Management (VP, Director, Manager)), do NOT call get_plan_metrix yet. List those matches (id, layer, name) and ask the user which to use, offering their OR combination as an option, then pull the data. answer_groups lists matches that are answers to the same catalog question, with the OR expression ready to offer. Args: query: Natural language audience description, e.g. "podcast listener", "venture capital", "angel investment", "horror movies", "TikTok user". layer: Optional data-layer filter. Accepts "iab" (IAB Digital Interests 2.0), "plan metrix" (the survey), or "demos". Omit to search every layer, which is usually right — the best segment for a query is often in a layer the caller did not think to ask for. limit: Max matches to return, default 10.
social_content
ChatGPTGets individual social posts for one or more properties and/or categories (Content Pulse). Args: entity_ids: Opaque property identifiers, as returned by social_search_properties or by an earlier social tool result — pass them verbatim, never guessed. names: Property or category names to resolve internally (e.g. "MrBeast", "F1 Drivers") — alternative to entity_ids, and the only way to include a category. A name that is ambiguous or unknown comes back under unresolved_names with candidate entity_ids to retry with. services: Platforms — facebook, instagram, twitter, youtube, tiktok. start_date: YYYY-MM-DD. end_date: YYYY-MM-DD. search_text: Optional free-text filter on post content. sort_by: Metric to sort by (default engagements = total_actions). limit: Max posts to return (default 50, capped at 500).
social_list_category_sets
ChatGPTLists predefined media indices (e.g. "U.S. Media 100 Index") that can be passed as category_set to social_power_rankings, instead of entity_ids. Use the returned name values verbatim.
social_list_metrics
ChatGPTLists the metric names accepted by social_metrics and social_power_rankings. Use the returned name values verbatim. trendable marks metrics that can be requested as a time series (granularity day/week/month) in social_metrics. Args: services: Optional filter — one or more of facebook, instagram, twitter, youtube, tiktok. Omit for all.
social_metrics
ChatGPTGets aggregate social metrics, or a trend series, for one or more properties and/or categories. granularity="none" returns one aggregate value per property/metric over the range. granularity="day"/"week"/"month" returns a time series (only trendable metrics — see social_list_metrics). Args: entity_ids: Opaque property identifiers, as returned by social_search_properties or by an earlier social tool result — pass them verbatim, never guessed. names: Property or category names to resolve internally (e.g. "MrBeast", "F1 Drivers") — alternative to entity_ids, and the only way to include a category. A name that is ambiguous or unknown comes back under unresolved_names with candidate entity_ids to retry with. metrics: Metric names from social_list_metrics (e.g. engagements, likes). services: Platforms to report — facebook, instagram, twitter, youtube, tiktok. start_date: YYYY-MM-DD. end_date: YYYY-MM-DD. granularity: none | day | week | month.
social_power_rankings
ChatGPTRanks properties and/or categories by social performance over a date range (Power Rankings). Pass entity_ids/names for an ad-hoc mix of properties and categories (e.g. "Man Utd", "Sport Players", "F1 Drivers"), OR pass category_set for a predefined media index (e.g. "U.S. Media 100 Index" — call social_list_category_sets for the full list). category_set cannot be combined with the others. Args: entity_ids: Opaque property identifiers to rank, as returned by social_search_properties or by an earlier social tool result — pass them verbatim, never guessed. names: Property or category names to resolve internally (e.g. "Man Utd", "F1 Drivers") — alternative to entity_ids, and the only way to rank a category. A name that is ambiguous or unknown comes back under unresolved_names with candidate entity_ids to retry with. start_date: YYYY-MM-DD. end_date: YYYY-MM-DD (max 365-day range). service: cross_platform (default), facebook, instagram, twitter, youtube. limit: Max ranked entities to return (default 25). category_set: Name of a predefined media index to rank instead of entity_ids/names — see social_list_category_sets for valid names.
social_search_properties
ChatGPTSearches this account's Social property list by name (brands/accounts). Use it to find the entity_id for a property, which every other social tool needs (or pass the name directly via the names param on those tools). The search is scoped to the properties on the account's own list, which for many accounts is a short one — so an empty result means only that nothing on this list is named like the query. It does not mean the brand is unmeasured, and it does not mean the account may not report on it: an entity_id obtained any other way still works, because properties are not per-user entitlements. Args: query: Free-text name to search for (e.g. "MrBeast"). limit: Max properties to return (default 20).
tv_demographics
ChatGPTStation demographic breakdown or national HH/demo universe estimates. TWO MODES: 1. Station Demographic Breakdown (set universe_estimates=False, default): Returns avg_aud by demographic group (income, race, education, country of origin). Requires markets or stations + period. 2. National HH/Demo Universe Estimates (set universe_estimates=True): Returns national_demo_universe for demographic groups. Use year + month instead of period. Args: period: Period string (mode 1). E.g. "Specific Time Range;2024-April-03-2024-April-09". markets: Market names (mode 1). In output, label these "Comscore market" (or "CM" after first use) — never any other market/region term. stations: Station call signs or names (mode 1). dayparts: Daypart filters (mode 1), e.g. ["All Week", "Weekdays"]. demo_groups: Demographic group names to look up. Examples: Mode 1: ["HHs W/ Race/Ethnicity", "Household Income", "Country of Origin", "HHs W/ Education"] Mode 2: ["A18+", "M18+", "W18+", "English more than Spanish", "Dog - Yes"] Also accepts a custom SEGMENT GROUP name or demo_group_no discovered via tv_search_demographics (e.g. "Political In-State NE v3 - 08.27.2018 to Ongoing" or 8541) — it resolves to the group's member segments automatically. Local-flagged groups break out per market; national-only groups will not return local data. universe_estimates: True → national universe estimates mode. year: Year for universe estimates mode (e.g. 2024). month: Month name for universe estimates mode (e.g. "April"). Examples: Station demographic breakdown — WABC, race/ethnicity tv_demographics( stations=["WABC New York, N.Y. (ABC)"], period="Specific Time Range;2024-April-03-2024-April-09", dayparts=["All Week"], demo_groups=["HHs W/ Race/Ethnicity"], ) National HH demo universe estimates tv_demographics( universe_estimates=True, demo_groups=["A18+", "M18+", "W18+"], year=2023, month="October", )
tv_market_viewership
ChatGPTNetwork viewership broken down by market — National Market widget. Args: period: Period string, e.g. "Specific calendar month;2023-November". markets: Market names, e.g. ["Portland, ME", "Abilene, TX"]. In output, label these "Comscore market" (or "CM" after first use) — never any other market/region term. networks: Network names, e.g. ["ABC", "A&E"]. None = all networks. metrics: Default: ["avg_aud", "rating", "num_hours"]. Options: "avg_aud", "rating", "num_hours", "market_index" (market vs national rating ratio ×100), "hh_universe" (household universe count), "market_rank" (market rank number). "Total Hours Viewed" → "num_hours"; "Market Index" → "market_index"; "Household Universe" → "hh_universe"; "Market Rnk"/"Market #" → "market_rank". group_by: Dimensions, e.g. ["market", "network"] (default), ["network"] (aggregate all selected markets per network), ["market"] (aggregate across networks per market), ["network", "day_of_week"]. When grouped by both market and network, a market-total rollup row (network_name "(N networks)") is inserted above each market's network rows. Example: tv_market_viewership( markets=["Portland, ME", "Abilene, TX"], networks=["ABC", "A&E"], period="Specific calendar month;2023-November", metrics=["avg_aud", "rating", "num_hours", "market_index"], group_by=["market", "network"], )
tv_retrieve_next_page
ChatGPTRetrieves the next page of results for a TV tool response that included a next_page_token. Each page's response carries its own next_page_token; a null token indicates the last page. Args: next_page_token: The token from the previous response's next_page_token field.
tv_schedule
ChatGPTProgram schedule — what aired on a station/network on a given day. Covers: Station Schedule widget. Scope: provide markets, stations, or networks (at least one). markets: Fetch schedule for all stations in these markets. stations: Specific station call signs or names. networks: Network name for national schedule lookup. Args: day: Date string, e.g. "2024-July-01" or "2024-07-01". fields: Columns to return (user-friendly OR API names). Default: all available. User-friendly → API name mappings: "Air Date" → "day" (broadcast date, formatted as 'Mon DD, YYYY') "Air Time" → "airdatetime" (broadcast start time, H:MM AM/PM local) "Run Time" → "duration_minutes" (program length in minutes, integer) "Series Name" → "series_name" "Episode Title" → "episode_title" Other API fields: "episode_no", "is_new_airing", "series_genre". NOTE: "Run Time" = duration in MINUTES (e.g. 30, 60), i.e. program length — not a time of day. "Air Time" is the broadcast clock time. Examples: Station schedule for ABC network on July 1 2024 tv_schedule(networks=["ABC"], day="2024-July-01", fields=["Run Time", "Series Name"]) Schedule for a specific station with Air Date, Air Time, Run Time, Series Name, Episode Title tv_schedule(stations=["ERC Washington, D.C. (Cozi TV)"], day="2025-July-01", fields=["Air Date", "Air Time", "Run Time", "Series Name", "Episode Title"])
tv_search_demographics
ChatGPTDiscover and resolve TV demographic/segment IDs — including Political, Automotive, Plan Metrix, and other custom audience segments. Common labels (A18-49, A25-54, M18-49, W25-54, HH, "household", etc.) do not need this tool — the high-level tools (tv_viewership_by_program, tv_viewership_by_time, tv_demographics) accept them directly via the demo/demo_groups parameter and resolve standard demos internally (e.g. demo="HH"). This tool covers everything else, via one of three modes: 1. LIST CATALOGS (no arguments): returns the segment "owner" families available — e.g. "Comscore Political Segments", "Comscore Automotive - Local", "Comscore Plan Metrix". Start here when a user mentions Political, Automotive, or Plan Metrix segments and you don't yet know what exists. 2. LIST GROUPS (owner=...): returns the demo groups under an owner, each with its demo_group_no, demo_group_name, and whether it is available locally/nationally. E.g. owner="Comscore Political Segments" returns per-state groups like "Political In-State NE v3 - 08.27.2018 to Ongoing" (group 8541). Groups flagged local can be broken out per market; national-only groups cannot. demo_local=true means the group is usable via tv_demographics only — it is not compatible with tv_viewership_by_program's demo parameter. 3. LIST SEGMENTS (group=...): returns the individual demo_no segments inside a group. Accepts the group name (exact) or its demo_group_no. E.g. group="Political In-State NE v3 - 08.27.2018 to Ongoing" returns the NE voter segments (Democratic/Republican/Independent turnout tiers) with their demo_no. demo_local=true on a segment means the same tv_demographics-only restriction applies as for groups. A resolved group name is accepted directly by tv_demographics(demo_groups=[...]) for an audience breakout, as are individual demo_no values. A free-text name fragment also works for a fuzzy substring search across all demos (e.g. "Hispanic A18-34", "WSIL"); results include the owning group for context. When no owner/group matches, the requested segment is not available in TV data. A fourth mode covers reverse ID lookup: 4. RESOLVE IDS (demo_nos=[...]): returns metadata for each demo_no — for feed/Snowflake-share clients that arrive with raw demo_no values and need the names back. Args: name: Optional free-text fragment for a fuzzy demo_name search. owner: Optional exact owner family name to list its groups (mode 2). Known owners include: Comscore Political Segments, Comscore Automotive - Local, Comscore Automotive - National, Comscore Plan Metrix. group: Optional group name (exact) or demo_group_no to list its member segments (mode 3). demo_nos: Optional list of demo_no values to resolve back to names/metadata (mode 4). Standard demos (no lookup needed; pass directly to high-level tools). "Persons N-M" and "AN-M" are different demographics — Persons demos measure people in the age range, A/M/W demos measure households containing someone in it — so pass whichever the request actually names, never the other: Persons: P2+ / HH=83841, Persons 18-49=83844, Persons 18+=83845, Persons 25-54=83849 (also Female/Male Persons variants, e.g. Male Persons 25-54=83885 — search by name for the rest). HHs w/ age range: A18-34=651, A18-49=3623, A25-49=5053, A25-54=652, A18+=46524, M18-49=3632, M25-49=3633, M25-54=3634, M18+=46525, W18-49=3641, W25-49=3642, W25-54=3643, W18+=46526.
tv_search_markets
ChatGPTFind a Comscore TV market by name fragment to get its market_no, or resolve a list of market_no IDs back to market metadata. Resolves a market name like "Abilene, TX" or "New York" to the market_no that local TV queries take. Pass "all" (or leave name empty) to list every Comscore market — never enumerate the footprint with letter-by-letter searches, and note that the viewership tools take markets=["all"] directly, so covering every market needs no lookup at all. Pass market_nos instead of name to reverse-resolve raw market_no values (e.g. from a Snowflake share or a data feed) back to market metadata. In every output — prose, headings, table columns, chart labels, and any Word/PPTX/PDF export — label these "Comscore market" (or "CM" after first use). No other market/region term or acronym is permitted. Args: name: Market name fragment (case-insensitive), e.g. "Abilene", "Boston", "New York". Empty or "all" returns every Comscore market. market_nos: Optional list of market_no values to resolve back to metadata. Mutually exclusive with a non-empty name.
tv_search_networks
ChatGPTResolves a TV network name to its network_no ID, or a set of network_no IDs back to names. Pass either name (fuzzy substring on network_name) or network_nos (exact reverse lookup by ID). Exactly one must be given. Args: name: Name fragment to search for (case-insensitive), e.g. "CNN", "NBC", "ESPN". network_nos: List of network_no values to resolve back to names/metadata.
tv_search_stations
ChatGPTFinds a specific local TV station by call sign or name to get its station_no, or resolves a list of station_no IDs back to station metadata (reverse lookup). Covers both broadcast affiliates (positive station_no) and cable networks (negative station_no). Pass either name (fuzzy match on call sign / station name, active stations only) or station_nos (exact reverse lookup by ID — for feed/Snowflake-share clients arriving with raw IDs; includes inactive stations so historical IDs still resolve). Args: name: Call sign or name fragment to search for (case-insensitive). Examples: "GBTS", "WBZ", "WCVB", "NBC", "Boston CBS", "crmz". market_no: Optional — restrict name results to stations whose primary market matches this market_no. Ignored when station_nos is given. tv_search_markets resolves a market name to market_no. station_nos: List of station_no values to resolve back to metadata (batched internally when large). Example — find GBTS in Boston: tv_search_stations(name="GBTS") by call sign tv_search_stations(name="NBC", market_no=2009) NBC affiliates in Boston tv_search_stations(station_nos=[4616, -54988, 14285]) reverse ID lookup
tv_viewership_by_program
ChatGPTProgram-level viewership ranked by audience. Covers: Local Ranker, Local Program-Based, National Ranker, National Program-Based, National Ad Report, Syndicated Series Reporting. Scope (provide at least one, or omit all for all national networks): markets: Market names, e.g. ["Abilene, TX", "Buffalo, NY"], or ["all"] for every Comscore market (no market lookups needed). Automatically fetches all stations in those markets. In output, label these "Comscore market" (or "CM" after first use) — never any other market/region term. stations: Station call signs or names, e.g. ["WABC", "KRBC Abilene, Texas (NBC)"] Can mix with markets. networks: Network names for national path, e.g. ["ABC", "NBC", "A&E"] Mutually exclusive with markets/stations. Args: period: "Specific broadcast month;2023-February" — that's the format. Other examples: "Specific calendar month;2023-November" "Specific Time Range;2024-March-13-2024-March-14" "Specific Day;2024-July-01" dayparts: Daypart names or clock hours, e.g. ["Prime", "14:00", "3am to 3am"]. Named: "Early Morning", "Daytime", "Early Fringe", "Prime Access", "Prime"/"Broadcast Prime", "Late Fringe", "Overnight". Clock hour: "02:00PM", "14:00", "07:00AM" → 1-hour window each. Multiple clock hours: pass each as a separate list item, e.g. ["12:00AM", "01:00AM"] for midnight-2am coverage (two 1-hour windows). Semicolon-separated string also works: "12:00AM;01:00AM". "3am to 3am" / "6am to 6am" / "All Week" = total day (no filter). days_of_week: Day filters, e.g. ["Monday", "Weekdays", "Friday"]. Can also be included in dayparts list. station_types: Which stations a markets scope expands to. Default (omitted) = local over-the-air broadcast stations only. Options: "broadcast" (OTA), "cable" (national cable feeds as carried in those markets — the only way to get cable viewing for a market), "independent", "all". dimension: What to rank rows by: "series" (default), "station", "network", "telecast", "newscasts", "genre". "series" aggregates each program to one row across the whole period — use this for "top N programs" questions. "telecast" returns one row per individual airing (each date + start_time is a separate row, so one program can appear dozens of times) — only use this when the request is specifically about individual broadcasts/airdates, not an aggregated ranking. demo: Demographic, e.g. "HH" (default), "A18-49", "W25-54", "M18-49". Pass the demographic the request NAMES, verbatim. "Persons 25-54" and "A25-54" are different demographics, not two spellings of one: Persons demos count people in the age range, A/M/W demos count households containing someone in it. A request for persons must be passed as "Persons 25-54" (likewise "Persons 18-49", "Persons 18+", "Male Persons 25-54", ...) — substituting the A-label silently returns another population's numbers. Multiple demos can be requested in a single call by separating them with semicolons, e.g. "A18-34;A18-49;A25-54;A55+". The first demo uses the bare metric name (e.g. avg_aud, rating); each additional demo gets its own column suffixed with the demo label, e.g. avg_aud_A18-49, rating_A55+, returning all demos in a single call. Custom segment IDs from tv_search_demographics (e.g. a Political, Automotive, or Plan Metrix demo_no) cannot be used here directly — pass them via demo_groups instead (see below). demo_groups: Cross-tab program rankings by a custom segment group discovered via tv_search_demographics — e.g. a Comscore Automotive, Political, or Plan Metrix group name/demo_group_no (owner "Comscore Automotive - Local" → group "Intent to Buy - Rollup Segments" → individual segments like "New Pickup"), or an individual demo_no/demo_name. Look up the exact group or segment first with tv_search_demographics — group/segment names are not guessable. Each entry adds an avg_aud/rating/share column for that segment alongside the primary demo (same one-column-per-demo pattern as semicolon-separated demo values) — rows stay grouped by the dimension (e.g. one row per program), now cross-tabbed with segment reach. Local-only groups only return dat…
tv_viewership_by_time
ChatGPTTime-slot viewership — ratings by quarter-hour, hour, day, or daypart. Covers: Local Time-Based, National Time-Based, Local Trender (Chart), National Trender (Chart), Time-Based Grid widgets. Scope (provide at least one, or omit for all national networks): markets: Market names, e.g. ["Abilene, TX"], or ["all"] for every Comscore market (no market lookups needed). In output, label these "Comscore market" (or "CM" after first use) — never any other market/region term. stations: Station call signs or names, e.g. ["KRBC Abilene, Texas (NBC)"] networks: Network names for national path, e.g. ["AMC", "ABC"] Args: period: Period string (same formats as tv_viewership_by_program). dayparts: Daypart names or clock hours to filter to. Days of week can also be included here. days_of_week: Day filters (can also go in dayparts). station_types: Which stations a markets scope expands to. Default (omitted) = local over-the-air broadcast stations only. Options: "broadcast" (OTA), "cable" (national cable feeds as carried in those markets — the only way to get cable viewing for a market), "independent", "all". granularity: Time resolution for rows: "qtr_hour" (default) — one row per 15-minute slot "hour" — one row per hour "day" — one row per broadcast day (Trender) "week" — one row per week "daypart" — one row per daypart passed in dayparts, all from a SINGLE request. Without it, multiple dayparts collapse into one combined number, so a per-daypart report needs one call per daypart. Use it whenever a request wants several dayparts broken out (e.g. all 7 standard dayparts). demo: Demographic, e.g. "HH", "A18-49". Pass the demographic the request NAMES, verbatim: "Persons 25-54" (people in the range) and "A25-54" (households containing someone in it) are different demographics, so substituting one for the other silently returns another population's numbers. Multiple demos can be requested in one call by separating with semicolons, e.g. "A18-34;A18-49;A55+" — each gets its own column suffixed with the demo label (rating_A18-49, avg_aud_A55+, ...), returning all demos in a single call. For BOTH "household metrics" and "demographic metrics" together (e.g. household "Live Share" + demographic "Share" with a stated demographic like A18+), demo="HH;A18+" combines them: the HH column covers the household metric and the demo column covers the demographic metric. metrics: Default: ["avg_aud", "rating"]. Options: "avg_aud", "rating", "share", "num_hours", "sets_in_use" (the "Sets In Use" / "SIU" / "QH SIU" metric — pass "Sets In Use" or "sets_in_use"). Like share, sets_in_use emits one column per demo (HH → "sets_in_use", demo → "sets_in_use_<demo>"). Every row also always includes meets_demo_threshold and meets_high_quality_demo_threshold for each non-HH demo requested (true/false) — surface these to flag suppressed/low-confidence figures (below 300 HH/25 hrs, or below 75 HH for the high-quality bar). The API only computes these for a demographic, so an HH-only request (demo="HH", the default) won't return them. stream: "live" (default), "live+3" / "c3", "live+7" / "c7". aggregate_stations: Collapse all stations in scope into one row per market (per time slot / daypart) by summing their audience — e.g. a single per-market "Cable" total with station_types=["cable"]. The row carries a stations count. Sums avg_aud / rating / share / num_hours (all additive over a market's stations); Sets In Use is a market-level level, so its maximum is kept rather than a sum. Local (markets/stations) queries only. limit: Maximum rows to return in total (default 100). Increase to fetch a full trender/time-grid. A scope over 300 stations is split into batched requests and merged; limit applies once, to that merged total, not per batch — raising it never shrinks any individual batch. Bulk-pull exception: granularity="daypart" on a batched scope (a full-footprint pull) returns EVERY (station, daypart) row and ignores limit — capping there would silently drop stations, and the caller would have to shard the market list by hand to get the whole answer. For a top-…
find_media
Claudeget_audience_overlap
Claudeget_cross_visiting
Claudeget_demographics
Claudeget_entity_status
Claudeget_metric
Claudeget_plan_metrix
Claudeget_top_entities
Claudeget_trend
Claudelist_metrics
Claudesearch_category
Claudesearch_plan_metrix_audience
Claudesocial_content
Claudesocial_list_category_sets
Claudesocial_list_metrics
Claudesocial_metrics
Claudesocial_power_rankings
Claudesocial_search_properties
Claudetv_demographics
Claudetv_market_viewership
Claudetv_retrieve_next_page
Claudetv_schedule
Claudetv_search_demographics
Claudetv_search_markets
Claudetv_search_networks
Claudetv_search_stations
Claudetv_viewership_by_program
Claudetv_viewership_by_time
Claude
