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-insensitivetrue): adds animage_urlfield to each result item returned byget_news_articles,get_youtube_videos,get_youtube_channels,get_news_moments, andget_trends. When the header is absent,image_urlis 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: valuelines for industry, business summary, mentality summary, mission, vision and value statements, and key terms[COMPANIES],[INFLUENCERS],[EVENTS],[SOCIAL_CAUSES],[PHILANTHROPIC_ORGANIZATIONS]: onename → relationship (type)line per related entity[OPINION_QUESTIONS],[SCENARIO_QUESTIONS]: onequestion → answerline 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_trends8 params - 2 examples
Discover macro cultural trends (long-term patterns) from news and social media. Does not cover YouTube; for how interest in a topic is moving on YouTube, use get_youtube_creator_insights with insight_type="trends".
Parameters:
search_terms(array, 0-3 terms, optional): Search terms. If not provided, returns top trends sorted by total article count (biggest trends first). When provided, do NOT also sendsort_by— the two parameters are mutually exclusivestart_date(string, optional): YYYY-MM-DD format, earliest 2026-01-01end_date(string, optional): YYYY-MM-DD format, earliest 2026-01-01brand(array, optional): Filter to trends that mention these brands (max 5, OR'd). Case-insensitive substring match against every brand on the trend, not only the 10 listed intop_brandsperson(array, optional): Filter to trends that mention these people (max 5, OR'd). Case-insensitive substring match against every person on the trend, not only the 10 listed intop_peoplesort_by(string, optional): Mutually exclusive withsearch_terms— sending both returns an error. Omit this parameter wheneversearch_termsis provided (results are then ranked by relevance automatically). Only set when no search terms are given. Values:"size"(default) = total article count (biggest trends first);"recency"= most recent trends first. Use"recency"only when the user explicitly requests chronological orderinglimit(int, optional): Results per search term (default: 3, max: 5)include_total_statistics(bool, optional, defaulttrue): Include theaggregate_statsblock of population statistics. Setfalsefor sample records only, which is significantly faster. See Aggregate Statistics
Each trend in sample_trends includes title, overview, bullet_points, start_date, end_date, total_moment_count, total_narrative_count, total_article_count, total_post_count, article_count_timeline and post_count_timeline (see Timelines), top_brands and top_people (up to 10 names each), and representative_moments and representative_narratives (up to 3 each, with title, summary, total_article_count or total_post_count, start_date and end_date).
Example with search terms:
{
"tool": "get_trends",
"arguments": {
"search_terms": ["AI", "automation"],
"brand": ["Microsoft", "Google"],
"limit": 5
}
}Example without search terms (browse top trends):
{
"tool": "get_trends",
"arguments": {
"start_date": "2024-11-01",
"end_date": "2024-11-30",
"limit": 5
}
}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 sendsort_by— the two parameters are mutually exclusivestart_date(string, optional): UTC ISO datetimeYYYY-MM-DDTHH:MM:SS, earliest2026-01-01T00:00:00. Supports hour/minute precision — for a whole-day search useT00:00:00end_date(string, optional): UTC ISO datetimeYYYY-MM-DDTHH:MM:SS, earliest2026-01-01T00:00:00. For a whole-day search useT23:59:59category(array, optional): Filter by content categories (max 5)entity(array, optional): Filter by entity names (max 5)sort_by(string, optional): Mutually exclusive withsearch_terms— sending both returns an error. Omit this parameter wheneversearch_termsis 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 orderinglimit(int, optional): Results per search term (default: 8, max: 20)include_total_statistics(bool, optional, defaulttrue): Include theaggregate_statsblock of population statistics. Setfalsefor 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 sendsort_by— the two parameters are mutually exclusivestart_date(string, optional): YYYY-MM-DD format, earliest 2026-01-01end_date(string, optional): YYYY-MM-DD format, earliest 2026-01-01sentiment(string, optional): Filter by sentiment:very_positive,positive,neutral,negative,very_negativeplatform(array, optional): Filter by platforms (max 5): X, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threadstheme(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, selectionentity(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, usesearch_termsinstead.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 — prefermin_likes/min_commentsfor 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'scountry_countsentry againsttotal_post_counton 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 withsearch_terms— sending both returns an error. Omit this parameter wheneversearch_termsis 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 orderinglimit(int, optional): Results per search term (default: 8, max: 20)include_total_statistics(bool, optional, defaulttrue): Include theaggregate_statsblock of population statistics. Setfalsefor sample records only, which is significantly faster. See Aggregate Statisticsinclude_original_text(bool, optional, defaultfalse): Addoriginal_textto each narrative'srepresentative_post— the post's text in the language it was written in. The defaulttextis always English; posts written in other languages are machine-translated on ingestion. Settrueonly 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 toostart_date(string, optional): UTC ISO datetimeYYYY-MM-DDTHH:MM:SS, earliest2026-01-01T00:00:00. Supports hour/minute precision — for a whole-day search useT00:00:00end_date(string, optional): UTC ISO datetimeYYYY-MM-DDTHH:MM:SS, earliest2026-01-01T00:00:00. For a whole-day search useT23:59:59publisher(string, optional): Filter by publisher namecategory(array, optional): Filter by content categories (max 5). Do not prefix values withnews/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 Countrieslanguage_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" coveragelimit(int, optional): Results per search term (default: 10, max: 50)include_total_statistics(bool, optional, defaulttrue): Include theaggregate_statsblock of population statistics. Setfalsefor sample records only, which is significantly faster. See Aggregate Statisticsinclude_full_body(bool, optional, defaultfalse): Return each article's full body text. By defaultbodyis truncated to 2,000 characters (at a word boundary) to keep responses small. Non-English articles also carryoriginal_title/original_bodywith 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 (useentityfor those). When unsure, favorsearch_terms. Pair withentityto find a topic about a named entitystart_date(string, optional): UTC ISO datetimeYYYY-MM-DDTHH:MM:SS, earliest2026-01-01T00:00:00. Supports hour/minute precision — for a whole-day search useT00:00:00end_date(string, optional): UTC ISO datetimeYYYY-MM-DDTHH:MM:SS, earliest2026-01-01T00:00:00. For a whole-day search useT23:59:59platform(array, optional): Filter by platforms (max 5): X, Reddit, Truth Social, Pinterest, Instagram, Bluesky, TikTok, Threadstheme(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, selectionentity(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 thansearch_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, usesearch_terms(and favorsearch_termswhen unsure). Combine withsearch_termsto 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. Prefermin_likes/min_commentsfor 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, whereasmin_likes/min_comments/min_sharesmeasure 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 isgb, Australia's isau). 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 withcountryto 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, defaulttrue): Include theaggregate_statsblock of population statistics. Setfalsefor sample records only, which is significantly faster. See Aggregate Statisticsinclude_full_body(bool, optional, defaultfalse): 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. Settrueonly when you need to read complete long-form postsinclude_original_text(bool, optional, defaultfalse): Addoriginal_textto each post — its text in the language it was written in. The defaulttextis always English; posts written in other languages are machine-translated on ingestion. Settrueonly 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 astext, 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 parameterscategory_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_PETSdate_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 isGB, Australia's isAU, the UAE's isAE, Japan's isJP, Portugal's isPT, South Korea's isKR, Vietnam's isVN). Lowercase codes are accepted and upcased. When omitted, returns hashtags across all available countrieslimit(int, optional): Number of results per search term or total results if no search term (default: 50, max: 200)include_total_statistics(bool, optional): Whenfalse, omitsaggregate_stats. Defaults totrue. 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 passXfor 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 optionssegments: 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 sendsort_by— the two parameters are mutually exclusivestart_date(string, optional): Start date for video publish date filtering (YYYY-MM-DD format, earliest 2005-02-14). Whileinclude_total_statisticsis true the range may not exceed 180 days; omit this to search the 180 days ending atend_date(or today)end_date(string, optional): End date for video publish date filtering (YYYY-MM-DD format, earliest 2005-02-14). Whileinclude_total_statisticsis true the range may not exceed 180 dayslanguage(array, optional): Filter by language codes (e.g., "en", "es") - max 5country(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 isGB, notUK. See Countriesiab_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 itis_short(boolean, optional): Filter by video type: true for Shorts, false for long-form, omit for allexclude_kids_content(boolean, optional): Exclude kids content when truemin_views(int, optional): Minimum view count thresholdmin_channel_subscribers(int, optional): Minimum channel subscriber countsort_by(string, optional): Mutually exclusive withsearch_terms— sending both returns an error. Omit this parameter wheneversearch_termsis 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 orderinglimit(int, optional): Results per search term (default: 10, max: 50)include_total_statistics(bool, optional, defaulttrue): Include theaggregate_statsblock of population statistics. Setfalsefor 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 sendsort_by— the two parameters are mutually exclusivestart_date(string, optional): Start date for latest video publish date filtering (YYYY-MM-DD format, earliest 2005-02-14). Whileinclude_total_statisticsis true the range may not exceed 180 days; omit this to search the 180 days ending atend_date(or today)end_date(string, optional): End date for latest video publish date filtering (YYYY-MM-DD format, earliest 2005-02-14). Whileinclude_total_statisticsis true the range may not exceed 180 dayslanguage(array, optional): Filter by language codes (e.g., "en", "es") - max 5country(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 isGB, notUK. See Countriesexclude_kids_content(boolean, optional): Exclude kids content when truemin_subscribers(int, optional): Minimum subscriber count thresholdmin_views(int, optional): Minimum total view count thresholdmin_video_count(int, optional): Minimum video count on channelsort_by(string, optional): Mutually exclusive withsearch_terms— sending both returns an error. Omit this parameter wheneversearch_termsis 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 orderinglimit(int, optional): Results per search term (default: 10, max: 50)include_total_statistics(bool, optional, defaulttrue): Include theaggregate_statsblock of population statistics. Setfalsefor 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 audiencetopic(string, optional): A subject in plain words (e.g."electric vehicles","Nike"). Matched internally to a Google Knowledge Graph entity; the match is returned asresolved_topicso an ambiguous term can be checked and retriedchannel_ids(array, optional, max 50): YouTube channel IDs such as"UCX6OQ3DkcsbYNE6H8uQQuVA". Channel names cannot be looked up here — get IDs fromget_youtube_channelsfirst. Only the firstlimitIDs are profiled (10 by default), and the rest are dropped without being reported, so raiselimitwhen passing more than 10. Not valid withinsight_type="trends", which returns an erroraudience_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,femaleaudience_interests(array, optional, max 5): Viewer interests in plain words (e.g."cooking"). Describes the audience's interests, whereastopicdescribes 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 errorcountry(string, optional, default"us"): ISO 3166-1 alpha-2 code in any case (the UK isgb, Japanjp, Indiain). 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 Countrieslimit(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 5include_brand_sentiment(bool, optional, defaultfalse): Only applies withinsight_type="trends"and atopicnaming 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 topicsinclude_top_videos(bool, optional, defaulttrue): Only applies to channel profiles. Setfalseto 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 searchedresolved_topic: the Knowledge Graph entity your topic text matched (query,name,machine_id,description), withother_matcheslisting alternativestotal_available/returned: how many creators, channels or trends matched, versus how many were returnedchannels_not_found: requested channel IDs Google did not recognisecreators[]: name, channel_id, handle, channel_created, country, languages, relevance, data_sharing_consent, metricsprofiles[]: name, channel_id, handle, channel_created, country, channel_type, languages, data_sharing_consent, metrics, plusaudience(viewer share by AGE_RANGE, GENDER, DEVICE, GEO_TARGET_COUNTRY),content_topics, andtop_videos(up to 5, each with video_id, title, views, likes, comments, published). Profiles carry norelevancetrends[]: 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, andpartnership_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_percentis a fraction (0.19= +19%). At the top level it compares the latest month with three months earlier; withinhistory, each month compares with the month beforeviews_indexedis 0–100 against the topic's own peak month, so it cannot be compared across topicsviewsis the absolute view count for the latest month only, and appears on just that month ofhistoryhistorycovers 36 months, newest first, for topic trends only. Audience trends returnaudience_shareinstead: the fraction of the requested audience that searched for or viewed the trendbrand_sentimentshares 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 whenget_youtube_creator_insightsfinds no creators, profiles, or trends. When at least one search term returns results, the terms without any come back with an emptysample_*list instead. - Invalid input: a tool error describing the problem, such as an unknown audience-targeting
platform,sort_bysent withsearch_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-DDfor trends, narratives, and the YouTube tools;YYYY-MM-DDTHH:MM:SSfor 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 termsaggregate_stats: population statistics (see Aggregate Statistics), omitted wheninclude_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, orsample_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_statisticsparameter uses it the same way:
- The seven search tools above return an
aggregate_statsblock (the total match count plus field distributions) by default. Passinclude_total_statistics=falsewhen you only need a few example records and not population-level statistics: theaggregate_statsblock is then omitted and the search is significantly faster.- For
get_youtube_videosandget_youtube_channels, leavinginclude_total_statisticsattruecaps the searched date range at 180 days (see Dates);include_total_statistics=falseremoves the cap.get_tiktok_hashtagsreturns anaggregate_statsblock per search result by default, computed over the returned rows rather than the full dataset;include_total_statistics=falseomits it (smaller response, no speed difference).- The
sample_*records are always returned and unaffected.
get_youtube_creator_insightshas noinclude_total_statisticsparameter.
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 withlanguage_code),date_distribution,likes_stats,comments_stats, andshares_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_distributionget_youtube_videos:total_matches,language_distribution,country_distribution,category_distribution,views_distribution,likes_distribution,date_distributionget_youtube_channels:total_matches,language_distribution,country_distribution,subscriber_distribution,date_distributionget_social_media_narratives:total_matches,total_post_count(combined posts across all matching narratives),sentiment_distribution(narrative counts keyednegative,neutral,positive),platform_distribution(keyed by the stored platform spelling, which can differ from theplatformfilter values, for examplebskyfor Bluesky andtruthsocialfor 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), andtotal_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_countandtotal_post_count(combined counts across all matching trends),top_brands_distributionandtop_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_distributionis{"interval": ..., "buckets": [{"date": ..., "count": ...}]}with up to 30 buckets. The interval (for example1d,7d, or1M) is chosen automatically to fit the searched range and is reported ininterval, so despite their names the*_per_day_date_distributionseries are not always daily. Bucket dates areYYYY-MM-DDfor narratives and the YouTube tools andYYYY-MM-DDTHH:MM:SSfor the rest. - Cluster dates: the
*_per_day_date_distributionseries count clusters, not their contents: when stories broke, conversations started, or trends concluded. For article or post volume over time, callget_news_articlesorget_social_media_posts, which bucket each record on its own publish date. - Sentiment bands:
sentiment_distributionhas three bands (negative,neutral,positive) while thesentimentfilter accepts five, so they do not map one to one: the distribution'snegativecovers everything the filter would callnegativeorvery_negative. Band edges are half-open, so a score of exactly25counts aspositivein the distribution but matchessentiment="neutral"when filtering. Narratives with no sentiment score appear in no band, so the bands need not sum tototal_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_distributionand narratives'country_distribution, 15 for articles' publishers, categories, and IAB categories and for videos'category_distribution, and 10 for every other one. The exception isget_tiktok_hashtags'stop_country_distribution, which counts every country code present in the returned rows'top_country_listvalues. - Engagement stats: each
*_statsobject hascount,min,max,avg, andsum.countreflects only the records that have a value for that metric, so compare it tototal_matchesto gauge coverage, which is lowest for shares. When no matching record has a value,countandsumare0andmin,max, andavgare 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 byget_trendsandget_social_media_narratives, earliest2026-01-01 - UTC ISO datetime format (
YYYY-MM-DDTHH:MM:SS, e.g.,"2026-05-13T12:05:18"): used byget_news_articles,get_news_moments, andget_social_media_postsfor hour/minute-precision filtering, earliest2026-01-01T00:00:00. Naive UTC — do not include a timezone offset. For a whole-day search useT00:00:00toT23: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 omittedstart_datedefaults to the 180 days ending atend_date(or today) instead of the earliest available date, and an explicit range wider than 180 days returns an error. The returnedsearch_start_dateandsearch_end_datealways state the range actually searched, and the records andaggregate_statsalways cover that same range. Sendinclude_total_statistics: falseto 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(orGB), neveruk. Aukvalue matches nothing on the search tools and returns an error onget_tiktok_hashtagsandget_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_byparameter: - 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_byis mutually exclusive withsearch_terms: For tools that acceptsort_by(get_trends,get_news_moments,get_social_media_narratives,get_youtube_videos,get_youtube_channels), sending bothsort_byandsearch_termsin the same request returns an error. When search terms are provided, results are automatically ranked by relevance — omitsort_byentirely.
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.