Documentation

Brand Mentality MCP Server - Client Documentation

The Brand Mentality MCP Server enables the intersection of real-time data listening and brand perception. The server provides Model Context Protocol (MCP) tools that allow clients to add these capabilities in conjunction with their existing data stack, enabling AI assistants and applications to access comprehensive brand profiles, discover cultural trends, and gather real-time insights from news articles and social media posts.

Key Capabilities

  • Brand Intelligence: Access detailed brand profiles including values, mission, vision, and brand positioning
  • Cultural Trend Analysis: Discover macro cultural trends and patterns by aggregating news moments and social media narratives
  • Real-Time News Insights: Find clustered news moments (day-to-day events) and search individual news articles
  • Social Media Intelligence: Track social media narratives (day-to-day conversations) and analyze individual posts
  • TikTok Trend Discovery: Get trending TikTok hashtags filtered by category, date range, country, and optional search terms
  • YouTube Intelligence: Search YouTube videos and channels from a curated dataset with filtering by language, country, categories, and engagement metrics
  • YouTube Creator Discovery: Find creators by topic or by who watches them, profile known channels including audience demographics and partnership eligibility, and track how interest in a topic is moving on YouTube
  • Audience Targeting: Generate platform-specific audience targeting segments for ad campaigns across multiple platforms

Data Hierarchy

The server organizes data in a hierarchical structure:

  • Individual Level: Articles and social media posts provide detailed, granular content
  • Cluster Level: Moments (news clusters) and Narratives (social media clusters) group related content
  • Trend Level: Trends aggregate moments and narratives to reveal long-term cultural patterns

     Social Posts ──► Narratives ──┐
                                   │
                                   ├──► Trends
                                   │
      Articles ──► Moments ────────┘

Hierarchy:

  • Social Posts → Clustered into Narratives (day-to-day conversations)
  • Articles → Clustered into Moments (day-to-day news events)
  • Narratives + Moments → Aggregated into Trends (long-term cultural patterns)

Connection

Protocol: Model Context Protocol (MCP) over HTTP Port: 8080 (default) Authentication: Authorization: Bearer <ACCESS_TOKEN>

All requests require the authentication token in the Authorization header.

Optional Headers:

  • X-Include-Image-URLs (case-insensitive true): adds an image_url field to each result item returned by get_news_articles, get_youtube_videos, get_youtube_channels, get_news_moments, and get_trends. When the header is absent, image_url is omitted to keep responses lean. Set it only if your client renders images.

Credentials: The MCP server URL and Access token will be provided by Sightly.

Note: The authorization method may change in future versions.

Array Parameters

Every parameter documented as an array below also accepts a string, for clients that cannot send real JSON arrays:

  • A JSON-encoded array, such as "[\"Nike\", \"Adidas\"]", is parsed into the equivalent array.
  • Any other string, such as "Nike", is treated as a single-element array.

Sending a real array is still preferred. The documented maximum item counts apply either way, and values are never split on commas, so "Nike, Adidas" is one value rather than two.

get_brand_profile1 params - 1 example

Get a brand's profile: industry, business and mentality summaries, mission, vision and value statements, key terms, related entities, and the brand's answers to opinion and scenario questions.

Note: Brand profiles must be created and submitted in Brand Mentality before they can be retrieved via this tool. Only profiles owned by your account or its child accounts are returned. brand_name is matched approximately, so close variants of the profile name still find it.

Parameters:

  • brand_name (string, required): Brand name

Returns: plain text, not JSON. It opens with a BRAND NAME: <name> line followed by bracketed sections, each omitted when empty:

  • [BRAND_INFORMATION]: Label: value lines for industry, business summary, mentality summary, mission, vision and value statements, and key terms
  • [COMPANIES], [INFLUENCERS], [EVENTS], [SOCIAL_CAUSES], [PHILANTHROPIC_ORGANIZATIONS]: one name → relationship (type) line per related entity
  • [OPINION_QUESTIONS], [SCENARIO_QUESTIONS]: one question → answer line per question

When no matching profile is found, the response is the plain message No profile found for <brand_name>.

Example:

{
  "tool": "get_brand_profile",
  "arguments": {
    "brand_name": "Nike"
  }
}

get_news_moments8 params - 3 examples

Find clustered news articles about topics (day-to-day events).

Parameters:

  • search_terms (array, 0-3 terms, optional): Search terms. If not provided, returns top moments sorted by article count (biggest story clusters first). When provided, do NOT also send sort_by — the two parameters are mutually exclusive
  • start_date (string, optional): UTC ISO datetime YYYY-MM-DDTHH:MM:SS, earliest 2026-01-01T00:00:00. Supports hour/minute precision — for a whole-day search use T00:00:00
  • end_date (string, optional): UTC ISO datetime YYYY-MM-DDTHH:MM:SS, earliest 2026-01-01T00:00:00. For a whole-day search use T23:59:59
  • category (array, optional): Filter by content categories (max 5)
  • entity (array, optional): Filter by entity names (max 5)
  • sort_by (string, optional): Mutually exclusive with search_terms — sending both returns an error. Omit this parameter whenever search_terms is provided (results are then ranked by relevance automatically). Only set when no search terms are given. Values: "size" (default) = article count (biggest story clusters first); "recency" = most recent moments first. Use "recency" only when the user explicitly requests chronological ordering
  • limit (int, optional): Results per search term (default: 8, max: 20)
  • include_total_statistics (bool, optional, default true): Include the aggregate_stats block of population statistics. Set false for sample records only, which is significantly faster. See Aggregate Statistics

Each moment in sample_news_moments includes title, summary, start_date, end_date, total_article_count, article_count_timeline (see Timelines), and a representative_article with title, url, published_at, publisher_name, publisher_domain and publisher_location.

Sensitive topics: each moment may include sensitive_topics, the brand-safety topics the moment substantially involves. Values come from: sex, drugs, crime, death, hacking, terrorism, tobacco, alcohol, military conflict, politics, obscenity, conspiracy, guns, human rights, kids channel, racism. An empty list means the moment was evaluated and none were flagged; the field is omitted for moments that have not been evaluated yet.

Example with search terms:

{
  "tool": "get_news_moments",
  "arguments": {
    "search_terms": ["climate change"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "category": ["environment"],
    "limit": 10
  }
}

Example narrowing to a specific hour band:

{
  "tool": "get_news_moments",
  "arguments": {
    "search_terms": ["breaking news"],
    "start_date": "2026-05-13T08:00:00",
    "end_date": "2026-05-13T10:00:00",
    "limit": 10
  }
}

Example without search terms (browse top moments):

{
  "tool": "get_news_moments",
  "arguments": {
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "limit": 10
  }
}

get_social_media_narratives15 params - 2 examples

Find clustered social media posts about topics (day-to-day conversations).

Parameters:

  • search_terms (array, 0-3 terms, optional): Search terms. If not provided, returns top narratives sorted by post count (most discussed first). When provided, do NOT also send sort_by — the two parameters are mutually exclusive
  • start_date (string, optional): YYYY-MM-DD format, earliest 2026-01-01
  • end_date (string, optional): YYYY-MM-DD format, earliest 2026-01-01
  • sentiment (string, optional): Filter by sentiment: very_positive, positive, neutral, negative, very_negative
  • platform (array, optional): Filter by platforms (max 5): X, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threads
  • theme (array, optional): Filter by themes (max 5): discounts, purchase, appearance, churn, cost, ads, experience, craftmanship, transaction, criminal, loyalty, stock, taste, temperature, ambiance, delivery, fit, injury, knowledge, leadership, comfort, access, illness, location, restrooms, speed, satisfaction, wait times, cleanliness, durability, friendliness, selection
  • entity (array, optional): Filter to narratives about a specific named person, brand, organization, product, event, or place (max 5) — e.g. ["Messi", "Nike"]. Case-insensitive substring; multiple values OR'd. Covers the ~two-thirds of narratives where an entity was detected. For broad topics/moods, use search_terms instead.
  • min_likes (int, optional): Only return narratives whose posts have at least this many likes in total (cluster-level engagement floor, must be ≥ 0). Narratives with no like total are excluded.
  • min_comments (int, optional): Only return narratives whose posts have at least this many comments in total (cluster-level engagement floor, must be ≥ 0). Narratives with no comment total are excluded.
  • min_shares (int, optional): Only return narratives whose posts have at least this many shares/reposts in total (cluster-level engagement floor, must be ≥ 0). Coverage is partial (present on roughly a quarter of narratives), so this can sharply narrow results — prefer min_likes/min_comments for general engagement filtering.
  • country (array, optional): Only return narratives with at least one post from these countries, as ISO 3166-1 alpha-2 codes (max 5, OR'd, any case) — e.g. ["gb", "au"]. This is an inclusion filter, not a dominance filter: a global narrative with a single UK post matches ["gb"]. Results rank by total post count, so the top ones are typically large global narratives in which the filtered country is a small fraction. To answer what a market is talking about, compare that country's country_counts entry against total_post_count on each record and discard the slivers; narrowing the date range to about a week gives a better candidate pool, but does not change the ordering. Roughly a third of posts have no known country and cannot be matched.
  • sort_by (string, optional): Mutually exclusive with search_terms — sending both returns an error. Omit this parameter whenever search_terms is provided (results are then ranked by relevance automatically). Only set when no search terms are given. Values: "size" (default) = post count (most discussed first); "recency" = most recent narratives first. Use "recency" only when the user explicitly requests chronological ordering
  • limit (int, optional): Results per search term (default: 8, max: 20)
  • include_total_statistics (bool, optional, default true): Include the aggregate_stats block of population statistics. Set false for sample records only, which is significantly faster. See Aggregate Statistics
  • include_original_text (bool, optional, default false): Add original_text to each narrative's representative_post — the post's text in the language it was written in. The default text is always English; posts written in other languages are machine-translated on ingestion. Set true only when the source-language wording matters (quoting verbatim, checking a translation, or showing a market's own words). It is absent for posts that were already English, and non-Latin scripts cost roughly four times the tokens of the English

Each narrative in sample_social_media_narratives includes title, summary, start_date, end_date, total_post_count, a representative_post with text, platform, post_publish_date and — when that post is still in the posts index, which is effectively always for recent narratives and around 60% across a year-long window — url and author_name, plus source_counts, the narrative's posts per source as {"source_type": <source>, "post_count": <int>} entries. Source values are the stored spellings (for example twitter.com), not the platform filter values. The representative_post text is English: non-English posts are machine-translated, so quote it as a translation rather than as the author's own words, and request include_original_text when you need what was actually written.

Each returned narrative also includes a sentiment_score — the cluster's overall sentiment on a -100 (most negative) to 100 (most positive) scale (omitted when unavailable). The sentiment filter buckets this score: very_negative (< -75), negative (< -25), neutral (-25…25), positive (> 25), very_positive (> 75). Each narrative also includes cluster-level engagement totals total_likes, total_comments, and total_shares (omitted when unavailable).

Each narrative also carries a per-country breakdown of where its posts come from: country_counts is an array of {"country": <lowercase ISO 3166-1 alpha-2>, "post_count": <int>} entries, and country_unclassified_count is the number of posts whose country could not be determined. Together they sum to total_post_count. Large narratives can span 100+ countries, so country_counts lists only the top 10 by post count and folds the remainder into a single {"country": "other", ...} entry. A narrative whose posts are all unclassified has an empty country_counts array and a non-zero country_unclassified_count.

Example with search terms:

{
  "tool": "get_social_media_narratives",
  "arguments": {
    "search_terms": ["AI"],
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "sentiment": "positive",
    "platform": ["X", "Reddit"]
  }
}

Example without search terms (browse top narratives):

{
  "tool": "get_social_media_narratives",
  "arguments": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "platform": ["X"],
    "limit": 10
  }
}

get_news_articles11 params - 3 examples

Search individual news articles (detailed content).

Parameters:

  • search_terms (array, 0-3 terms, optional): Keep complete concepts together (e.g., "renewable energy policy" not ["renewable", "energy"]). If not provided, returns most recent articles sorted by publish date. Non-English articles carry an English machine translation alongside the original text, and searches match both — so English search terms find foreign-language coverage, and source-language terms work too
  • start_date (string, optional): UTC ISO datetime YYYY-MM-DDTHH:MM:SS, earliest 2026-01-01T00:00:00. Supports hour/minute precision — for a whole-day search use T00:00:00
  • end_date (string, optional): UTC ISO datetime YYYY-MM-DDTHH:MM:SS, earliest 2026-01-01T00:00:00. For a whole-day search use T23:59:59
  • publisher (string, optional): Filter by publisher name
  • category (array, optional): Filter by content categories (max 5). Do not prefix values with news/
  • entity (array, optional): Filter by entity names (max 5)
  • publisher_location (string, optional): Filter by the publisher's country, as one full English country name: United States, United Kingdom, Canada, Germany, Spain, Turkey, South Africa, Nigeria, China, India, Philippines, Thailand, Mexico, Brazil, Argentina, France, Italy, Netherlands, Australia, Poland, United Arab Emirates, Japan. Articles with no recorded publisher location never match. See Countries
  • language_code (array, optional): Filter by the article's original language as lowercase ISO 639-3 codes (max 5) — e.g. ["spa", "deu"]. Values are OR'd. Supported (English plus 17 non-English): eng, spa, deu, fra, ita, pol, nld, ara, jpn, por, zho, hin, tur, tha, rus, kor, fas, vie. Coverage is partial — only newer articles carry a language code, and articles without one are excluded by this filter, so use it to narrow by language rather than to find "all English" coverage
  • limit (int, optional): Results per search term (default: 10, max: 50)
  • include_total_statistics (bool, optional, default true): Include the aggregate_stats block of population statistics. Set false for sample records only, which is significantly faster. See Aggregate Statistics
  • include_full_body (bool, optional, default false): Return each article's full body text. By default body is truncated to 2,000 characters (at a word boundary) to keep responses small. Non-English articles also carry original_title/original_body with the source-language text; these come pre-truncated to roughly 500 characters from the source pipeline and are unaffected by this flag

Each article in sample_news_articles includes title, body, url, published_at, publisher_name, publisher_domain, publisher_location, categories, entities, scenarios, and language_code (the ISO 639-3 original language; omitted when unknown). Fields with no value are omitted.

Example with search terms:

{
  "tool": "get_news_articles",
  "arguments": {
    "search_terms": ["renewable energy policy"],
    "publisher_location": "United States",
    "limit": 20
  }
}

Example narrowing to a specific hour band:

{
  "tool": "get_news_articles",
  "arguments": {
    "search_terms": ["product launch"],
    "start_date": "2026-05-13T08:00:00",
    "end_date": "2026-05-13T10:00:00",
    "limit": 20
  }
}

Example without search terms (browse recent articles):

{
  "tool": "get_news_articles",
  "arguments": {
    "publisher_location": "United States",
    "category": ["technology"],
    "limit": 20
  }
}

get_social_media_posts16 params - 6 examples

Search individual social media posts (detailed content).

Parameters:

  • search_terms (array, 0-3 terms, optional): Keep complete concepts together. If not provided, returns most recent posts sorted by publish date. Use for topics, themes, concepts, or moods — anything that is not a specific named person/brand/product/event/place (use entity for those). When unsure, favor search_terms. Pair with entity to find a topic about a named entity
  • start_date (string, optional): UTC ISO datetime YYYY-MM-DDTHH:MM:SS, earliest 2026-01-01T00:00:00. Supports hour/minute precision — for a whole-day search use T00:00:00
  • end_date (string, optional): UTC ISO datetime YYYY-MM-DDTHH:MM:SS, earliest 2026-01-01T00:00:00. For a whole-day search use T23:59:59
  • platform (array, optional): Filter by platforms (max 5): X, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threads
  • theme (array, optional): Filter by themes (max 5): discounts, purchase, appearance, churn, cost, ads, experience, craftmanship, transaction, criminal, loyalty, stock, taste, temperature, ambiance, delivery, fit, injury, knowledge, leadership, comfort, access, illness, location, restrooms, speed, satisfaction, wait times, cleanliness, durability, friendliness, selection
  • entity (array, optional): Filter to posts about a specific named person, brand, organization, product, event, or place (max 5) — e.g. "Messi", "Nike", "FIFA World Cup". Use this (rather than search_terms) when the user names such a thing; it is more precise for named subjects but only covers the ~half of posts where an entity was detected. Matching is case-insensitive substring ("contains") — "messi" matches "Lionel Messi", "world cup" matches "FIFA World Cup"; multiple values are OR'd. Use short, distinctive fragments (very short terms like "cup" can over-match). For broad topics/themes/moods, use search_terms (and favor search_terms when unsure). Combine with search_terms to find a topic about a named entity — e.g. entity: ["Nike"] + search_terms: ["product recall"].
  • min_likes (int, optional): Only return posts with at least this many likes (engagement floor, must be ≥ 0). Posts with no like count are excluded.
  • min_comments (int, optional): Only return posts with at least this many comments (engagement floor, must be ≥ 0). Posts with no comment count are excluded.
  • min_shares (int, optional): Only return posts with at least this many shares/reposts (engagement floor, must be ≥ 0). Coverage is partial and platform-dependent — many platforms do not report shares, so this filter excludes most posts and can sharply narrow results. Prefer min_likes/min_comments for general engagement filtering.
  • min_author_followers (int, optional): Only return posts whose author has at least this many followers (audience-reach floor, must be ≥ 0). Use this for questions about influential or large accounts — it measures the author's reach, whereas min_likes/min_comments/min_shares measure how an individual post performed. Posts with no follower count are excluded, which drops platforms that have no follower concept (Reddit, Facebook, Tumblr) entirely; follower counts are present on roughly three quarters of posts overall.
  • country (array, optional): Filter by the post's country of origin as ISO 3166-1 alpha-2 codes (max 5, OR'd, any case) — e.g. ["us", "gb"] (the UK's code is gb, Australia's is au). About half of all posts carry a country; the rest are excluded by this filter, so it narrows by geography rather than finding every post from a country. Best-covered countries: us, th, gb, in, br, fr, tr, mx.
  • language_code (array, optional): Filter by the post's detected language as lowercase ISO 639-1 codes (max 5, OR'd), e.g. ["en", "ja"]. Values must be lowercase; "JA" matches nothing. Pair with country to get a language within a market, since the two differ (posts from Japan are roughly a third English). Populated on about 88% of posts; posts with no detected language are excluded by this filter.
  • limit (int, optional): Results per search term (default: 10, max: 50)
  • include_total_statistics (bool, optional, default true): Include the aggregate_stats block of population statistics. Set false for sample records only, which is significantly faster. See Aggregate Statistics
  • include_full_body (bool, optional, default false): Return each post's full text. By default post text is truncated to 2,000 characters (at a word boundary) to keep responses small; most posts are shorter than that and are unaffected. Set true only when you need to read complete long-form posts
  • include_original_text (bool, optional, default false): Add original_text to each post — its text in the language it was written in. The default text is always English; posts written in other languages are machine-translated on ingestion. Set true only when the source-language wording matters (quoting verbatim, checking a translation, or showing a market's own words). It is absent for posts that were already English, obeys the same truncation as text, and non-Latin scripts cost roughly four times the tokens of the English

Each post in sample_social_media_posts includes text, platform, url, post_publish_date, author_name, and themes. Each also includes likes, comments, and shares fields (integer like/favorite, comment/reply, and share/repost counts; omitted when the platform does not expose them — shares in particular is sparsely populated), author_followers (the posting account's follower count, a proxy for reach; omitted on platforms with no follower concept and where the account was not resolved), an entities array (named entities detected in the post; empty or omitted when none were detected), country (ISO 3166-1 alpha-2 origin country code; omitted when unknown), and language_code (ISO 639-1 detected language of the post text; omitted when detection failed).

Post text is English. Posts written in other languages are machine-translated on ingestion, and original_text carries the source-language wording when you request it with include_original_text; it is absent for posts that were already English, which makes its presence a reliable signal that the post was not written in English. Search runs against the English text and is matched both by keyword and semantically, so a query in one language retrieves posts written in another; use language_code when you need results restricted to posts originally written in a particular language.

Example with search terms:

{
  "tool": "get_social_media_posts",
  "arguments": {
    "search_terms": ["climate action"],
    "platform": ["X"],
    "theme": ["experience"],
    "limit": 25
  }
}

Example narrowing to a specific hour band:

{
  "tool": "get_social_media_posts",
  "arguments": {
    "search_terms": ["product launch"],
    "start_date": "2026-05-13T08:00:00",
    "end_date": "2026-05-13T10:00:00",
    "limit": 25
  }
}

Example without search terms (browse recent posts):

{
  "tool": "get_social_media_posts",
  "arguments": {
    "platform": ["Reddit"],
    "theme": ["experience"],
    "limit": 25
  }
}

Example filtering by entity (substring/contains match):

{
  "tool": "get_social_media_posts",
  "arguments": {
    "entity": ["Messi", "World Cup"],
    "limit": 25
  }
}

Example filtering by engagement (only higher-engagement posts):

{
  "tool": "get_social_media_posts",
  "arguments": {
    "search_terms": ["product launch"],
    "min_likes": 100,
    "min_comments": 10,
    "limit": 25
  }
}

Example filtering by market and language (Japanese-language posts from Japan):

{
  "tool": "get_social_media_posts",
  "arguments": {
    "search_terms": ["product launch"],
    "country": ["jp"],
    "language_code": ["ja"],
    "limit": 25
  }
}

get_tiktok_hashtags6 params - 2 examples

Get trending TikTok hashtags. Can optionally filter by search terms or get top hashtags by category and date range.

Parameters:

  • search_terms (array, 0-3 terms, optional): Optional search terms to filter results. If not provided, returns top hashtags according to other parameters
  • category_name (string, optional): Filter by TikTok category. When omitted, a query with search terms spans all categories, while a query without search terms defaults to the cross-category "ALL" leaderboard. Available categories: ALL, ACADEMIC_RESOURCES, ANIMATION_AND_COMICS, APPAREL_AND_ACCESSORIES, ART, AUTOMOTIVE, BABY_CARE, BABY_KIDS_AND_MATERNITY, BEAUTY, BEAUTY_AND_PERSONAL_CARE, BEAUTY_SERVICES, BUSINESS_AND_FINANCE, BUSINESS_SERVICES, CARD_AND_BOARD_GAMES, CAREER_AND_PROFESSIONAL_GROWTH, COLLEGE, COMEDY, COMMUNITY_UPDATES_AND_ISSUES, CONVENTIONAL_AND_MAINSTREAM_SPORTS, COOKING, CRAFTING_AND_CREATIONS, CULTURE, DANCE, DIARY_AND_VLOG, DRINKS, EATING_EXPERIENCES, EDUCATION, ENTERTAINMENT_AND_SPORTS_NEWS, ENVIRONMENT, EXERCISE_AND_FITNESS, EXTREME_AND_ADVENTURE_SPORTS, FAMILY, FINANCIAL_SERVICES, FOOD, FOOD_AND_BEVERAGE, FOOD_RECOMMENDATIONS, GADGETS_AND_INNOVATION, GAMES, GENERAL_TRAVEL, HAIR_CARE, HEALTH, HEALTH_AND_WELLNESS, HISTORY_AND_LITERATURE, HOME_AND_GARDEN, HOME_IMPROVEMENT, HOUSEHOLD_PRODUCTS, LEARNING_AND_DEVELOPMENT, LEISURE_AND_RECREATION_FACILITIES, LIFE_SERVICES, LIVESTOCK_AND_FARMING, MISCELLANEOUS_PERFORMANCES, MOVIES_AND_TV, MUSIC, NEWS_AND_ENTERTAINMENT, OTHER_BEAUTY, OTHER_FASHION, OTHER_TRANSPORTATION, OUTDOOR_RECREATION, OUTFITS, PERFORMING_ARTS, PERSONAL_PHOTOGRAPHY, PETS, PET_CARE_AND_ACCESSORIES, PHOTOGRAPHY, PRODUCTIVITY_AND_EFFICIENCY, ROMANCE, SCIENCE, SENSORY_EXPERIENCES, SHOWS_FESTIVALS_AND_EXHIBITIONS, SOFTWARE_AND_APPS, SPECIAL_EFFECTS, SPORTS, SPORTS_AND_OUTDOOR, SUPERNATURAL_AND_HORROR, TECHNOLOGY, TOYS_COLLECTIBLES_AND_MEMORABILIA, TRAVEL, VEHICLE_AND_TRANSPORTATION, VIDEO_GAMES, WILDLIFE_AND_EXOTIC_PETS
  • date_range (string, optional): Filter by date range (default: "1DAY"). Available options: "1DAY", "7DAY", "30DAY", "120DAY"
  • country (array, optional): Filter by country, as uppercase ISO 3166-1 alpha-2 codes (max 5). Supported: US, GB, CA, DE, ES, TR, ZA, NG, CN, IN, PH, TH, MX, BR, AR, FR, IT, NL, PL, AU, AE, JP, PT, KR, VN (the UK's code is GB, Australia's is AU, the UAE's is AE, Japan's is JP, Portugal's is PT, South Korea's is KR, Vietnam's is VN). Lowercase codes are accepted and upcased. When omitted, returns hashtags across all available countries
  • limit (int, optional): Number of results per search term or total results if no search term (default: 50, max: 200)
  • include_total_statistics (bool, optional): When false, omits aggregate_stats. Defaults to true. Unlike the other tools, these statistics are computed over the returned rows (not the full dataset), so disabling them reduces response size but does not speed up the search

Response: search_results holds one entry per search term, or a single unlabeled entry when browsing without search terms. Each entry carries its own hashtags rows and, when include_total_statistics is true, an aggregate_stats block describing exactly those rows:

{
  "search_results": [
    {
      "search_term": "sports",
      "aggregate_stats": {
        "views_distribution": [
          {"range": "0-100K", "count": 4},
          {"range": "100K-1M", "count": 22},
          {"range": "1M-10M", "count": 18},
          {"range": "10M-100M", "count": 5},
          {"range": "100M+", "count": 1}
        ],
        "posts_distribution": [
          {"range": "0-1K", "count": 12},
          {"range": "1K-10K", "count": 26},
          {"range": "10K-100K", "count": 12},
          {"range": "100K-1M", "count": 0},
          {"range": "1M+", "count": 0}
        ],
        "rank_change_distribution": {"new": 28, "up": 11, "down": 9, "unchanged": 2},
        "top_country_distribution": {"US": 34, "GB": 9, "CA": 7}
      },
      "hashtags": [ ... ]
    }
  ]
}

Each row in hashtags includes hashtag_name, rank_position, rank_change (a string: "NEW" or a signed position change), posts, posts_global_lifetime, views, views_global_lifetime, category_name, country_code, date_range, created_at, top_country_list, audience_ages, and trending_history. Fields with no value are omitted.

All statistics describe the returned rows, never the full dataset. views_distribution and posts_distribution always list every bucket, so a count of 0 means no returned row fell in that range, and a row whose value is missing or non-numeric falls in no bucket. rank_change_distribution buckets each row's rank change in the order new, up, down, unchanged; rows with a missing or unrecognized rank change are skipped, and buckets with no rows are omitted. Expect new to dominate, since most hashtags in this dataset are new on any given day. top_country_distribution counts how often each country appears across the rows' top-country lists, most frequent first; unlike other top_-prefixed distributions it is exhaustive over the returned rows rather than truncated.

Example:

{
  "tool": "get_tiktok_hashtags",
  "arguments": {
    "search_terms": ["fitness"],
    "category_name": "EXERCISE_AND_FITNESS",
    "date_range": "7DAY",
    "limit": 20
  }
}

Example without search terms:

{
  "tool": "get_tiktok_hashtags",
  "arguments": {
    "category_name": "BEAUTY",
    "date_range": "1DAY",
    "limit": 15
  }
}

get_audience_targeting3 params - 2 examples

Generate audience targeting segments for specific ad platforms based on an audience description.

Parameters:

  • audience_name (string, required): The name of the audience to target (e.g., "Tech Enthusiasts", "Fitness Enthusiasts")
  • audience_description (string, required): A description of the audience to target (e.g., "Young professionals interested in technology and innovation")
  • platform (string, required): Which platform to target. Available platforms: Programmatic, YouTube, Pinterest, LinkedIn, TikTok, Snapchat, Meta, X, Reddit, Spotify, Search. Matched case-insensitively; any other value returns an error listing the valid options. Always pass X for Twitter

Platform-Specific Targeting Types:

  • YouTube: detailed_demographics, life_events, affinity_audiences, in_market_audiences, topics, keywords
  • Programmatic: categories, genres, ctv_segments, olv_segments
  • TikTok: interests, video_interactions, creator_interactions, hashtags
  • Meta: detailed_demographics, interests, behaviors
  • Snapchat: lifestyles, shoppers, visitors
  • LinkedIn: company_industries, member_interests, member_traits
  • X: interests, keywords, hashtags
  • Pinterest: interests, keywords
  • Spotify: interests, music_genres, playlist_themes, podcast_topics
  • Reddit: interest_groups, keywords
  • Search: keywords

keywords and hashtags are written for the audience rather than chosen from the platform's published segment list. Every other targeting type is chosen from that list.

Returns: a JSON object with two keys, both varying by platform:

  • demographics: age, gender, income, parental status and similar options. YouTube and Search share the same demographic options
  • segments: one list per targeting type above

Example:

{
  "tool": "get_audience_targeting",
  "arguments": {
    "audience_name": "Tech Enthusiasts",
    "audience_description": "Young professionals aged 25-35 interested in technology, innovation, and startups",
    "platform": "Meta"
  }
}

Example for YouTube:

{
  "tool": "get_audience_targeting",
  "arguments": {
    "audience_name": "Fitness Enthusiasts",
    "audience_description": "Adults interested in fitness, health, and wellness",
    "platform": "YouTube"
  }
}

get_youtube_videos13 params - 3 examples

Search individual YouTube videos by keyword and publish date, from the Brand Mentality curated YouTube dataset. Returns videos, not creator analysis; for audience, engagement or partnership questions, use get_youtube_creator_insights.

Parameters:

  • search_terms (array, 0-3 terms, optional): Search terms for video title/description. If not provided, returns top videos sorted by view count (highest first). When provided, do NOT also send sort_by — the two parameters are mutually exclusive
  • start_date (string, optional): Start date for video publish date filtering (YYYY-MM-DD format, earliest 2005-02-14). While include_total_statistics is true the range may not exceed 180 days; omit this to search the 180 days ending at end_date (or today)
  • end_date (string, optional): End date for video publish date filtering (YYYY-MM-DD format, earliest 2005-02-14). While include_total_statistics is true the range may not exceed 180 days
  • language (array, optional): Filter by language codes (e.g., "en", "es") - max 5
  • country (array, optional): Filter by the channel's country as uppercase ISO 3166-1 alpha-2 codes (e.g., "US", "GB") - max 5. Case-sensitive: lowercase codes match nothing, and the UK's code is GB, not UK. See Countries
  • iab_category (array, optional): Filter by IAB taxonomy category names (e.g., "Sports", "Music") - max 5. Case-insensitive substring match, so "Sports" also matches more specific categories that contain it
  • is_short (boolean, optional): Filter by video type: true for Shorts, false for long-form, omit for all
  • exclude_kids_content (boolean, optional): Exclude kids content when true
  • min_views (int, optional): Minimum view count threshold
  • min_channel_subscribers (int, optional): Minimum channel subscriber count
  • sort_by (string, optional): Mutually exclusive with search_terms — sending both returns an error. Omit this parameter whenever search_terms is provided (results are then ranked by relevance automatically). Only set when no search terms are given. Values: "size" (default) = view count (most viewed first); "recency" = newest videos first. Use "recency" only when the user explicitly requests chronological ordering
  • limit (int, optional): Results per search term (default: 10, max: 50)
  • include_total_statistics (bool, optional, default true): Include the aggregate_stats block of population statistics. Set false for sample records only, which is significantly faster. See Aggregate Statistics

Each video in sample_youtube_videos includes title, description, video_id, url, published (ISO datetime), views, likes, duration (seconds), is_short, language, country, categories, channel_id, channel_title, and channel_subscribers. Fields with no value are omitted.

Example with search terms:

{
  "tool": "get_youtube_videos",
  "arguments": {
    "search_terms": ["tech reviews"],
    "language": ["en"],
    "country": ["US"],
    "min_views": 10000,
    "limit": 20
  }
}

Example with subscriber filter (videos from larger channels):

{
  "tool": "get_youtube_videos",
  "arguments": {
    "search_terms": ["weight loss treatments"],
    "min_channel_subscribers": 100000,
    "limit": 20
  }
}

Example without search terms (browse top videos):

{
  "tool": "get_youtube_videos",
  "arguments": {
    "iab_category": ["Sports"],
    "is_short": false,
    "exclude_kids_content": true,
    "limit": 25
  }
}

get_youtube_channels12 params - 3 examples

Search YouTube channels by keyword in their title or description, from the Brand Mentality curated YouTube dataset. Carries no audience or engagement data; pass channel_id values from here to get_youtube_creator_insights for a full profile.

Parameters:

  • search_terms (array, 0-3 terms, optional): Search terms for channel title/description. If not provided, returns top channels sorted by subscriber count (highest first). When provided, do NOT also send sort_by — the two parameters are mutually exclusive
  • start_date (string, optional): Start date for latest video publish date filtering (YYYY-MM-DD format, earliest 2005-02-14). While include_total_statistics is true the range may not exceed 180 days; omit this to search the 180 days ending at end_date (or today)
  • end_date (string, optional): End date for latest video publish date filtering (YYYY-MM-DD format, earliest 2005-02-14). While include_total_statistics is true the range may not exceed 180 days
  • language (array, optional): Filter by language codes (e.g., "en", "es") - max 5
  • country (array, optional): Filter by the channel's country as uppercase ISO 3166-1 alpha-2 codes (e.g., "US", "GB") - max 5. Case-sensitive: lowercase codes match nothing, and the UK's code is GB, not UK. See Countries
  • exclude_kids_content (boolean, optional): Exclude kids content when true
  • min_subscribers (int, optional): Minimum subscriber count threshold
  • min_views (int, optional): Minimum total view count threshold
  • min_video_count (int, optional): Minimum video count on channel
  • sort_by (string, optional): Mutually exclusive with search_terms — sending both returns an error. Omit this parameter whenever search_terms is provided (results are then ranked by relevance automatically). Only set when no search terms are given. Values: "size" (default) = subscriber count (most popular first); "recency" = recently active channels first. Use "recency" only when the user explicitly requests chronological ordering
  • limit (int, optional): Results per search term (default: 10, max: 50)
  • include_total_statistics (bool, optional, default true): Include the aggregate_stats block of population statistics. Set false for sample records only, which is significantly faster. See Aggregate Statistics

Each channel in sample_youtube_channels includes title, description, channel_id, url, subscribers, video_count, total_views, latest_video_published (ISO datetime), language, country, and categories. Fields with no value are omitted.

Example with search terms:

{
  "tool": "get_youtube_channels",
  "arguments": {
    "search_terms": ["cooking recipes"],
    "language": ["en"],
    "min_views": 1000000,
    "limit": 15
  }
}

Example with subscriber filter (larger channels only):

{
  "tool": "get_youtube_channels",
  "arguments": {
    "search_terms": ["personal finance"],
    "country": ["US"],
    "language": ["en"],
    "min_subscribers": 5000,
    "limit": 20
  }
}

Example without search terms (browse top channels):

{
  "tool": "get_youtube_channels",
  "arguments": {
    "country": ["US"],
    "exclude_kids_content": true,
    "min_video_count": 50,
    "limit": 20
  }
}

get_youtube_creator_insights10 params - 4 examples

Discover and analyse YouTube creators, and track content trends, using Google's YouTube advertising data.

This is distinct from get_youtube_videos and get_youtube_channels, which search Sightly's own curated corpus by keyword and date. Use those for historical content search; use this one for creator discovery, partnership suitability, audience composition and trend trajectories.

Three creator modes, mutually exclusive — provide exactly one of topic, channel_ids, or the audience filters:

| Mode | Use when | Returns | |------|----------|---------| | topic | Finding creators who cover a subject | Creators ranked by relevance to that topic | | channel_ids | You already know the channels | Full profiles, the only mode with audience demographics and top videos | | audience filters | Finding creators by who watches them | Creators whose viewers match the profile |

Parameters:

  • insight_type (string, optional, default "creators"): "creators" finds or profiles creators; "trends" returns three years of monthly trend history for a topic, or what is trending for an audience
  • topic (string, optional): A subject in plain words (e.g. "electric vehicles", "Nike"). Matched internally to a Google Knowledge Graph entity; the match is returned as resolved_topic so an ambiguous term can be checked and retried
  • channel_ids (array, optional, max 50): YouTube channel IDs such as "UCX6OQ3DkcsbYNE6H8uQQuVA". Channel names cannot be looked up here — get IDs from get_youtube_channels first. Only the first limit IDs are profiled (10 by default), and the rest are dropped without being reported, so raise limit when passing more than 10. Not valid with insight_type="trends", which returns an error
  • audience_age_ranges (array, optional, max 5): Viewer age ranges: 18-24, 25-34, 35-44, 45-54, 55-64, 65+
  • audience_genders (array, optional, max 5): Viewer genders: male, female
  • audience_interests (array, optional, max 5): Viewer interests in plain words (e.g. "cooking"). Describes the audience's interests, whereas topic describes what the creator makes content about. Each interest is matched to a Google Knowledge Graph entity, and an interest that cannot be matched returns an error
  • country (string, optional, default "us"): ISO 3166-1 alpha-2 code in any case (the UK is gb, Japan jp, India in). Creator results, audience data and trends are all specific to this country. Supports the 219 countries Google Ads can target, which excludes Taiwan (tw), Hong Kong (hk), and Puerto Rico (pr); any other code returns an error. See Countries
  • limit (int, optional): Defaults to 15 for creator searches and 10 for channel profiles (max 50 there, 100 otherwise). Ignored for trends, which return at most 5
  • include_brand_sentiment (bool, optional, default false): Only applies with insight_type="trends" and a topic naming a brand, and is ignored otherwise. Returns up to 6 months of positive/neutral/negative view share plus AI-written summaries of what drove the positive and negative sentiment, derived from video content only (never comments). Restricts the topic match to brands, so it fails for non-brand topics
  • include_top_videos (bool, optional, default true): Only applies to channel profiles. Set false to roughly halve the response when you need only channel metrics and audience demographics

Data sharing consent: Google gates non-public fields behind each creator's consent. When data_sharing_consent is false, engagement_rate, the per-video averages, languages and audience are absent rather than zero for that creator. Roughly a quarter of creators withhold consent, and large official channels often do.

No pagination: Google returns roughly a thousand creators per search with no paging. total_available reports how many matched; raise limit rather than expecting a second page.

Example — find creators covering a topic:

{
  "tool": "get_youtube_creator_insights",
  "arguments": {
    "topic": "electric vehicles",
    "country": "us"
  }
}

Example — profile known channels (the only way to get audience demographics):

{
  "tool": "get_youtube_creator_insights",
  "arguments": {
    "channel_ids": ["UCX6OQ3DkcsbYNE6H8uQQuVA"],
    "include_top_videos": true
  }
}

Example — find creators by their audience:

{
  "tool": "get_youtube_creator_insights",
  "arguments": {
    "audience_age_ranges": ["25-34", "35-44"],
    "audience_interests": ["sustainable fashion"],
    "country": "gb"
  }
}

Example — brand sentiment on YouTube:

{
  "tool": "get_youtube_creator_insights",
  "arguments": {
    "insight_type": "trends",
    "topic": "Nike",
    "include_brand_sentiment": true
  }
}

Response fields:

  • country: the country searched
  • resolved_topic: the Knowledge Graph entity your topic text matched (query, name, machine_id, description), with other_matches listing alternatives
  • total_available / returned: how many creators, channels or trends matched, versus how many were returned
  • channels_not_found: requested channel IDs Google did not recognise
  • creators[]: name, channel_id, handle, channel_created, country, languages, relevance, data_sharing_consent, metrics
  • profiles[]: name, channel_id, handle, channel_created, country, channel_type, languages, data_sharing_consent, metrics, plus audience (viewer share by AGE_RANGE, GENDER, DEVICE, GEO_TARGET_COUNTRY), content_topics, and top_videos (up to 5, each with video_id, title, views, likes, comments, published). Profiles carry no relevance
  • trends[]: name, trend direction, views, views_indexed, audience_share, change_percent, history (monthly), brand_sentiment (per month: month, positive, neutral, negative, positive_summary, negative_summary)
  • metrics: subscribers, views, videos, likes, comments, shorts_views, shorts_videos, engagement_rate, avg_views_per_video, avg_likes_per_video, avg_comments_per_video, is_active_shorts_creator, is_active_live_stream_creator, and partnership_opportunities (advertising products the creator is eligible for)

Reading trends:

  • Trend data lags by roughly two months; the newest month is the latest Google has published
  • change_percent is a fraction (0.19 = +19%). At the top level it compares the latest month with three months earlier; within history, each month compares with the month before
  • views_indexed is 0–100 against the topic's own peak month, so it cannot be compared across topics
  • views is the absolute view count for the latest month only, and appears on just that month of history
  • history covers 36 months, newest first, for topic trends only. Audience trends return audience_share instead: the fraction of the requested audience that searched for or viewed the trend
  • brand_sentiment shares are proportions of views and sum to 1 per month. Months Google lacks enough data for carry no shares

Output Format

Every tool returns its result as a single text block. Read the entire text block — do not assume the context and the payload are delivered as separate parts.

  • Results found: the data context (guidance on how to interpret the payload), a blank line, then the payload. The payload is JSON for every tool except get_brand_profile, which returns plain text (see get_brand_profile).
  • Nothing found: a short plain-text message with no context and no JSON, such as No News Articles found for: <terms>. Try broader search terms or expand the date range. This happens when no search term returns a result, when no brand profile matches, and when get_youtube_creator_insights finds no creators, profiles, or trends. When at least one search term returns results, the terms without any come back with an empty sample_* list instead.
  • Invalid input: a tool error describing the problem, such as an unknown audience-targeting platform, sort_by sent with search_terms, or a YouTube date range wider than 180 days.

Search Tool Payloads

get_trends, get_news_moments, get_social_media_narratives, get_news_articles, get_social_media_posts, get_youtube_videos, and get_youtube_channels share one shape:

  • search_start_date / search_end_date: the range actually searched. YYYY-MM-DD for trends, narratives, and the YouTube tools; YYYY-MM-DDTHH:MM:SS for moments, articles, and posts.
  • search_results: one entry per search term, or a single entry when browsing without search terms. Each entry holds:
    • search_term: the term, omitted when browsing without search terms
    • aggregate_stats: population statistics (see Aggregate Statistics), omitted when include_total_statistics=false
    • the sample list: sample_trends, sample_news_moments, sample_social_media_narratives, sample_news_articles, sample_social_media_posts, sample_youtube_videos, or sample_youtube_channels

aggregate_stats.total_matches is the number of records matching the query in the whole database, while the sample_* list holds representative examples capped by limit. Fields with no value are omitted from records rather than returned as null.

The other tools have their own shapes, described in their sections: get_tiktok_hashtags returns hashtags rows with statistics over those rows, get_youtube_creator_insights returns creators, profiles, or trends with total_available and returned, get_audience_targeting returns demographics and segments, and get_brand_profile returns plain text.

Population statistics are configurable. Computing them is expensive, so every tool with an include_total_statistics parameter uses it the same way:

  • The seven search tools above return an aggregate_stats block (the total match count plus field distributions) by default. Pass include_total_statistics=false when you only need a few example records and not population-level statistics: the aggregate_stats block is then omitted and the search is significantly faster.
  • For get_youtube_videos and get_youtube_channels, leaving include_total_statistics at true caps the searched date range at 180 days (see Dates); include_total_statistics=false removes the cap.
  • get_tiktok_hashtags returns an aggregate_stats block per search result by default, computed over the returned rows rather than the full dataset; include_total_statistics=false omits it (smaller response, no speed difference).
  • The sample_* records are always returned and unaffected.

get_youtube_creator_insights has no include_total_statistics parameter.

Aggregate Statistics

The seven search tools above return full aggregate statistics per search term by default (omitted when include_total_statistics=false). Statistics cover every record matching that search term's query, not just the returned sample. When you pass search_terms, that population is the set matched by the term's query; when you browse without search terms, it is the whole filtered date range.

Distributions over multi-valued fields (a narrative's platforms, an article's categories) count a record in every bucket it belongs to, so those buckets can sum to more than total_matches.

  • get_social_media_posts: total_matches, platform_distribution, top_themes_distribution, language_distribution (posts per detected ISO 639-1 language code; use it to see the language mix of a market before narrowing with language_code), date_distribution, likes_stats, comments_stats, and shares_stats (engagement summaries over matching posts; see the engagement stats note below)
  • get_news_articles: total_matches, top_publishers_distribution, top_categories_distribution, top_iab_categories_distribution, publisher_location_distribution, language_code_distribution, date_distribution
  • get_youtube_videos: total_matches, language_distribution, country_distribution, category_distribution, views_distribution, likes_distribution, date_distribution
  • get_youtube_channels: total_matches, language_distribution, country_distribution, subscriber_distribution, date_distribution
  • get_social_media_narratives: total_matches, total_post_count (combined posts across all matching narratives), sentiment_distribution (narrative counts keyed negative, neutral, positive), platform_distribution (keyed by the stored platform spelling, which can differ from the platform filter values, for example bsky for Bluesky and truthsocial for Truth Social), country_distribution (posts summed per country across all matching narratives, keyed by lowercase ISO code), narrative_size_distribution (narratives bucketed by post count: 0-10, 10-25, 25-50, 50-100, 100+), narratives_per_day_date_distribution (narratives counted by earliest post date), and total_likes_stats, total_comments_stats, total_shares_stats (summaries of each narrative's engagement totals; see the engagement stats note below)
  • get_news_moments: total_matches, total_article_count (combined articles across all matching moments), moment_size_distribution (moments bucketed by article count: 0-5, 5-10, 10-25, 25-100, 100+), moments_per_day_date_distribution (moments counted by earliest article date)
  • get_trends: total_matches, total_article_count and total_post_count (combined counts across all matching trends), top_brands_distribution and top_people_distribution (how many matching trends list each name — not mention counts, and not limited to the 10 entities shown on each trend record), trends_per_day_date_distribution (trends counted by latest publish date)

Notes on reading these:

  • Date distributions: every *date_distribution is {"interval": ..., "buckets": [{"date": ..., "count": ...}]} with up to 30 buckets. The interval (for example 1d, 7d, or 1M) is chosen automatically to fit the searched range and is reported in interval, so despite their names the *_per_day_date_distribution series are not always daily. Bucket dates are YYYY-MM-DD for narratives and the YouTube tools and YYYY-MM-DDTHH:MM:SS for the rest.
  • Cluster dates: the *_per_day_date_distribution series count clusters, not their contents: when stories broke, conversations started, or trends concluded. For article or post volume over time, call get_news_articles or get_social_media_posts, which bucket each record on its own publish date.
  • Sentiment bands: sentiment_distribution has three bands (negative, neutral, positive) while the sentiment filter accepts five, so they do not map one to one: the distribution's negative covers everything the filter would call negative or very_negative. Band edges are half-open, so a score of exactly 25 counts as positive in the distribution but matches sentiment="neutral" when filtering. Narratives with no sentiment score appear in no band, so the bands need not sum to total_matches.
  • Which buckets appear: range distributions (size, views, likes, subscribers, sentiment) list every band, including empty ones. Date distributions include empty periods between the first and last matching record as count: 0, so gaps are visible rather than collapsed. Distributions keyed by value (platforms, themes, languages, countries, publishers, categories, brands, people) list only values with at least one match, so a missing key means a count of zero or a value outside the most frequent ones.
  • Truncation: distributions keyed by value list only the most frequent values, whether or not their name starts with top_: 20 for posts' top_themes_distribution and narratives' country_distribution, 15 for articles' publishers, categories, and IAB categories and for videos' category_distribution, and 10 for every other one. The exception is get_tiktok_hashtags's top_country_distribution, which counts every country code present in the returned rows' top_country_list values.
  • Engagement stats: each *_stats object has count, min, max, avg, and sum. count reflects only the records that have a value for that metric, so compare it to total_matches to gauge coverage, which is lowest for shares. When no matching record has a value, count and sum are 0 and min, max, and avg are omitted.

TikTok Hashtags returns aggregate_stats per search result (omitted when include_total_statistics=false): views_distribution, posts_distribution, rank_change_distribution, and top_country_distribution. These describe the returned rows rather than the full dataset. See get_tiktok_hashtags for details.

Timelines

article_count_timeline (trends and moments) and post_count_timeline (trends) show a record's own volume over its lifetime. When a record has 14 or fewer days of activity, each active day gets an entry: {"count": <int>, "day": <date>} for trends and {"article_count": <int>, "day": <date>} for moments. Records with 15 to 90 days are grouped into 7-day entries and longer ones into calendar months, each shaped {"date_range": "<first day> to <last day>", "count": <int>}.

Example Response Structure

A get_social_media_posts response:

{
  "search_start_date": "2026-05-01T00:00:00",
  "search_end_date": "2026-05-31T23:59:59",
  "search_results": [
    {
      "search_term": "AI",
      "aggregate_stats": {
        "total_matches": 15420,
        "platform_distribution": {"X": 8500, "Reddit": 4200, "TikTok": 2720},
        "top_themes_distribution": {"experience": 3200, "knowledge": 2800},
        "language_distribution": {"en": 12100, "es": 1450, "ja": 980},
        "date_distribution": {"interval": "1d", "buckets": [{"date": "2026-05-01T00:00:00", "count": 520}, ...]},
        "likes_stats": {"count": 14200, "min": 0, "max": 84210, "avg": 312.5, "sum": 4437500},
        "comments_stats": {"count": 13980, "min": 0, "max": 9120, "avg": 27.4, "sum": 383052},
        "shares_stats": {"count": 1120, "min": 0, "max": 4300, "avg": 18.2, "sum": 20384}
      },
      "sample_social_media_posts": [
        { "text": "...", "platform": "X", "url": "...", "post_publish_date": "...", "likes": 1280, "comments": 64, "shares": 22, "entities": ["Lionel Messi", "FIFA World Cup"], ... }
      ]
    }
  ]
}

Dates

  • Date-only format (YYYY-MM-DD, e.g., "2024-01-15"): used by get_trends and get_social_media_narratives, earliest 2026-01-01
  • UTC ISO datetime format (YYYY-MM-DDTHH:MM:SS, e.g., "2026-05-13T12:05:18"): used by get_news_articles, get_news_moments, and get_social_media_posts for hour/minute-precision filtering, earliest 2026-01-01T00:00:00. Naive UTC — do not include a timezone offset. For a whole-day search use T00:00:00 to T23:59:59.
  • YouTube tools (videos, channels): earliest 2005-02-14
  • Default: If not provided, uses the earliest available date as the start
  • What the range filters on: an article's or post's publish date, a moment's or narrative's earliest article or post, a trend's latest publish date, a video's publish date, and a channel's latest video publish date
  • YouTube tools with include_total_statistics: true (the default): the searched range is capped at 180 days. An omitted start_date defaults to the 180 days ending at end_date (or today) instead of the earliest available date, and an explicit range wider than 180 days returns an error. The returned search_start_date and search_end_date always state the range actually searched, and the records and aggregate_stats always cover that same range. Send include_total_statistics: false to search the full history without population statistics.

Countries

Each tool supports a different set of countries and expects its own code format:

| Tool | Parameter | Format | Supported countries | |------|-----------|--------|---------------------| | get_social_media_posts | country (where the post came from) | ISO 3166-1 alpha-2, any case | Any country. About half of posts carry one. Highest volume: us, th, gb, in, br, fr, tr, mx. Posts from us, gb, ca, au, and jp carry the fullest enrichment (themes, entities, follower counts) | | get_social_media_narratives | country (at least one post from it) | ISO 3166-1 alpha-2, any case | Any country. Roughly a third of posts have no known country | | get_news_articles | publisher_location (the publisher's country) | Full English name, one value | United States, United Kingdom, Canada, Germany, Spain, Turkey, South Africa, Nigeria, China, India, Philippines, Thailand, Mexico, Brazil, Argentina, France, Italy, Netherlands, Australia, Poland, United Arab Emirates, Japan | | get_tiktok_hashtags | country | ISO 3166-1 alpha-2, uppercase (lowercase is upcased) | US, GB, CA, DE, ES, TR, ZA, NG, CN, IN, PH, TH, MX, BR, AR, FR, IT, NL, PL, AU, AE, JP, PT, KR, VN | | get_youtube_videos | country (the channel's country) | ISO 3166-1 alpha-2, uppercase only | Any country | | get_youtube_channels | country (the channel's country) | ISO 3166-1 alpha-2, uppercase only | Any country | | get_youtube_creator_insights | country (default us) | ISO 3166-1 alpha-2, any case | The 219 countries Google Ads can target. Not Taiwan (tw), Hong Kong (hk), or Puerto Rico (pr) | | get_trends, get_news_moments, get_audience_targeting, get_brand_profile | None | | No country filter |

Two rules apply everywhere:

  • The UK's code is gb (or GB), never uk. A uk value matches nothing on the search tools and returns an error on get_tiktok_hashtags and get_youtube_creator_insights.
  • A country outside a tool's fixed list (get_news_articles, get_tiktok_hashtags, get_youtube_creator_insights) returns an error. On the tools that accept any country, an unknown or wrongly cased code returns no results rather than an error.

Search Terms

  • 0-3 terms per request (optional for every tool that accepts them)
  • Terms run in parallel when provided
  • For articles/posts: Keep complete concepts together
    • ✅ ["renewable energy policy"]
    • ❌ ["renewable", "energy", "policy"]
  • Without search terms: Tools return results sorted by a logical default, customizable with sort_by parameter:
    • Trends: default "size" (biggest trends), optional "recency" (most recent trends)
    • Moments: default "size" (biggest story clusters), optional "recency" (most recent moments)
    • Narratives: default "size" (most discussed), optional "recency" (most recent narratives)
    • Articles: sorted by publish date (most recent)
    • Posts: sorted by publish date (most recent)
    • TikTok Hashtags: sorted by rank position
    • YouTube Videos: default "size" (highest view count), optional "recency" (newest videos)
    • YouTube Channels: default "size" (highest subscriber count), optional "recency" (recently active channels)
  • sort_by is mutually exclusive with search_terms: For tools that accept sort_by (get_trends, get_news_moments, get_social_media_narratives, get_youtube_videos, get_youtube_channels), sending both sort_by and search_terms in the same request returns an error. When search terms are provided, results are automatically ranked by relevance — omit sort_by entirely.

Tool Selection

  • Brand info → get_brand_profile
  • Long-term trends in news and social media → get_trends
  • News clusters → get_news_moments
  • Social clusters → get_social_media_narratives
  • Individual articles → get_news_articles
  • Individual posts → get_social_media_posts
  • Trending TikTok hashtags → get_tiktok_hashtags
  • YouTube videos matching a keyword → get_youtube_videos
  • YouTube channels matching a keyword → get_youtube_channels
  • Audience targeting segments → get_audience_targeting
  • YouTube creators to partner with, their audience, or YouTube topic trends → get_youtube_creator_insights

The three YouTube tools cover different ground. get_youtube_videos and get_youtube_channels search Sightly's curated historical corpus by keyword and date — use them to find content that was published. get_youtube_creator_insights uses Google's advertising data — use it to discover creators, judge partnership suitability, see who watches a channel, or track a topic's trajectory. Channel IDs flow one way: look a channel up with get_youtube_channels, then pass its ID to get_youtube_creator_insights for the audience profile.

Call more than one of these tools for the same question only when chaining channel IDs as above, or when the user asks for both sources. get_trends covers news and social media, not YouTube. No tool ranks channels by growth or momentum, so a request for "trending channels" is answered by the single best-fitting tool, with that limitation stated.

Scroll to Top

Request Segments

Email *
First name *
Last name *
Company *
Preferred DSP
DSP Seat ID