Audiense Insights

Retrieve a comprehensive summary of an Audiense Insights report Args: id: The ID of the report to fetch. If you don't know the ID, use the search tool. detail: Level of detail for the response (optional, defaults to "full"): - "full": Use it to get the full data including influencers and insights for all segments - "summary": Use it to get basic report info without detailed segment analysis Returns: - id. - title. - status. - default baseline id - segmentation type: AFFINITIES or INTERCONNECTIONS. - Full audience details: cluster_id, size, top 10 influencers, top 5 insights. - Segments details: cluster_id, title, size, top 10 influencers, top 5 insights. - Network graph image. - Private URL. - Public URL. Notes: - Influencers' uniqueness is calculated using the default baseline for the full audience, and the full audience as baseline for the clusters. - Influencers retrieved are the top 10 influencers sorted by uniqueness. - If you need more than the top 10 influencers or insights, or getting that using different criteria, use the insights-get-report-influencers and insights-get-report-insights tools. - The insights retrieved are the top 5 values sorted by percentage for each of the following fields: bio_keyword, country, age, city, language, gender, interest. - For retrieving shared and influential content data, use the insights-get-report-content tool. - The default baseline id is the id of a baseline that can be used in the get-influencers tool. - To know more info about the default baseline use the get-baselines tool

Analyzes a list of influencer screen names and suggests cluster names where they appear, along with the average relevance score for each cluster. Args: screenNames: Array of Twitter/X screen names to analyze (e.g., ["AOC", "KamalaHarris"]) Returns: - clusters: Top 10 cluster suggestions sorted by average relevance scores

Creates a new Audiense Insights report whose audience is defined using one of two MUTUALLY EXCLUSIVE methods: Method 1 - Profile Attributes (combined with AND operation): - handles: Array of X account handles to analyze their followers - bio_keywords: Keywords in user bios (max 10,000) - country: ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "ES") You can use any combination of these parameters together. Method 2 - Conversations: - query: X API boolean expression for filtering conversations - start_date: Optional start date (YYYY-MM-DD) - end_date: Optional end date (YYYY-MM-DD, max 90 days range) Use the conversations parameter which is an object with query, start_date, and end_date. For query syntax and operators specification, see: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#enterprise-operators CRITICAL CONSTRAINTS: - These methods are MUTUALLY EXCLUSIVE - DO NOT use country parameter with conversations parameter. - DO NOT use handles or bio_keywords with conversations parameter - If user requests location filtering with conversations, use the X operators in the query string - The country parameter only works with profile attributes (Method 1), not with conversations (Method 2) The report uses affinities segmentation and takes 15-60 minutes to generate.

Retrieves available baselines. This list contains baselines for countries and gender, for each contry there are three baselines: - General: All genders. i.e: US - General - Male: Only male. i.e: US - Male - Female: Only female. i.e: US - Female Args: - country: ISO country code to filter by. Ignored if ID is provided. - id: Specific baseline ID to retrieve. When provided, other filters are ignored. Returns: - id: The ID of the baseline. - label: The name of the baseline. - country_iso_code: The ISO country code of the baseline. - gender: The gender of the baseline. Usage notes: - When ID is provided, it takes precedence and other filters are ignored. Otherwise, can be filtered by country. - This baselines can be used only for fetching influencers with the get-report-influencers tool. - This baselines cannot be used for fetching information from insights or content tools

Retrieves the list of available influencer categories that can be used as the categories parameter in the insights-get-report-influencers tool.

Retrieves content that the audience engages with online. IMPORTANT: Both content_type and content_items are required to retrieve data. Call without parameters first to see available options. Args: - cluster_id: The cluster to retrieve content for - content_type: Required for data. "influential" or "shared" - content_items: Required for data. Array of content types to retrieve - count: Optional. Limit results to top N items Returns: - Without required params: List of available content_type and content_items options - With required params: The filtered content data Content sections: - sharedContent: Content posted by the audience - influentialContent: Content from accounts the audience follows

Retrieves the influencers of a cluster compared with a baseline cluster. Returns: - Each influencer includes: - screen name - profile image URL - description - location - followers count - networks - categories - Affinity (%): The level of alignment between the influencer and the audience. - Baseline Affinity (%): The influencer's affinity within the baseline audience - Uniqueness Score: A measure of how distinct the influencer is within the selected audience compared to the baseline. - Times More Likely: How many times more likely the audience is to follow this influencer compared to the baseline. (Represent it with an x, ie: 1.5x or 2x) Sorting options: - sort_by='uniqueness' (default): Get most distinctive influencers first (unique to this audience) - sort_by='affinity': Get most aligned influencers first (highest engagement with audience) - sort_by='times_more_likely': Get influencers with highest likelihood ratio first (audience most over-indexes on these) - direction='desc' (default): Highest values first - direction='asc': Lowest values first (useful to find least unique or least aligned influencers) Usage notes: - It's a good practice to limit the amount of influencers returned on each request (use pagination if required). - The baseline is determined as follows: - If the selection was the full audience and no other baseline_cluster_id is provided, then use the default_baseline_id of the report. - If the selection was a specific segment, the full audience is used as the baseline. - Filtering influencers helps to find more relevant influencers for your use case. Use the insights-get-influencer-categories tool to retrieve the list of available categories.

Retrieves aggregated insights for a cluster. IMPORTANT: Call this tool without the 'insights' parameter first to discover available insights for the cluster, then make a second call specifying which insights you need. Args: - cluster_ids: Array of cluster_ids (1-20 clusters). Duplicates are automatically removed. - insights: Optional list of insight names to retrieve. If omitted, returns the list of available insights for discovery. Returns: - Without insights param: List of available insight names for the cluster - With insights param: The requested insights data with statistical distributions: - Demographics (e.g., gender, age, country). - Behavioral traits (e.g., active hours, platform usage). - Psychographics (e.g., personality traits, interests). - Socioeconomic factors (e.g., income, education status). Usage notes: - First call without insights to discover what's available - Then call with specific insights you need to minimize response size If multiple clusters are provided its a good practice to filter which insights to get, that way the response is more manageable.

Updates the title and/or color of one or multiple clusters in an Intelligence Report. At least one property (title or color) must be provided for each cluster to update.

Search for insights reports by name. If the query is empty, it will return all reports. Args: query: The query string for filtering reports by title. Returns: A list of reports matching the query, each with: - id: Unique report identifier (24-char hex string, e.g. "67f7dc0faf298e4e7dd8e3cf"). Use this id with the fetch, insights, content, and influencers tools. - title: Report name. - status: Report processing status. - segmentation_type: Type of audience segmentation used. - created_at: Report creation timestamp.