Audiense Insights

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.

insights-create-report

Returns information about the currently authenticated user including email, plan, and subdomain if applicable

whoami

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

fetch

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

insights-get-report-content

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.

insights-get-report-insights

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

insights-get-baselines

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

insights-get-influencer-categories

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.

insights-get-report-influencers

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.

search

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

insights-cluster-names