> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/bringing-in-your-feedback/social-listening.md). # Social Listening **Agents** let BAI go out and collect feedback from the open web on your behalf (public reviews, social posts, news mentions, video comments) and bring everything back into the same Feedback Groups your surveys and connector data live in. One agent can watch many platforms at once, and the data is normalised into the same analytical model as everything else, so themes and sentiment span every source. This page covers agents end-to-end: which platforms are supported, how to create one, how the intensity tiers and credits work, and how scraped data shows up in your dashboards. For other ways to bring feedback in, see [Creating a Survey](/boundaryai-docs/bringing-in-your-feedback/surveys/editor.md), [Uploading an Existing Dataset](/boundaryai-docs/bringing-in-your-feedback/uploading-an-existing-dataset.md), and [Connecting your tools](/boundaryai-docs/bringing-in-your-feedback/connect-to-your-existing-systems.md). *** ### When to use an agent Use an agent when: * You want to **track a brand or product** across review sites (Google Reviews, Trustpilot, TripAdvisor) without manually exporting reviews on a schedule. * You want **social listening** on your own channels or specific accounts (X / Twitter, Reddit, Instagram, LinkedIn, Facebook, YouTube, TikTok). * You want to monitor **press and news mentions** of a topic, product, or competitor (Google News). * You want public feedback to flow into the same Feedback Group as your surveys and support tickets, so themes can be compared across channels. If what you want to know is **how AI assistants describe your brand** (ChatGPT, Claude, Gemini, Perplexity, and others), that's a separate source type built on the same wizard: see [AI Visibility](/boundaryai-docs/bringing-in-your-feedback/ai-visibility.md). If the data already lives in a tool you control (a help-desk, a Jira project, a CRM), use a Connector instead. Connectors authenticate as you and pull native objects directly. Scrapers go after public data via web automation. *** ### Supported sources Twelve social-listening platforms are supported today, grouped by what they're best at: #### Review sites | Platform | Identifier | Notes | | ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Google Reviews** | Google Maps URL or place name | Star ratings preserved; auto-detects place if you give it a business name. | | **Trustpilot** | Company review URL | Country subdomains supported (`trustpilot.com`, `.de`, `.co.uk`, etc.) so multi-region brands can be tracked under one agent. | | **TripAdvisor** | Listing URL | Hotel, restaurant, attraction, etc. | | **Avis Vérifiés** | Company review-page URL | French verified-reviews platform (avis-verifies.com). | #### Social platforms | Platform | Identifier | Captures | | --------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **X (Twitter)** | Hashtags + account handles | Tweets matching the filters. | | **Reddit** | Subreddits (+ optional keyword filters) | Posts and comments; configurable sort order. | | **Instagram** | Profile URL | Posts and comments. | | **Facebook** | Page URL | Posts and comments. | | **LinkedIn** | Profile, company, or school URL | Posts and comments. | | **YouTube** | Video URL, or a channel URL (up to 10 per agent) | Comments, with exact posted dates. A channel URL pulls comments from every video the channel published within your chosen timeframe. | | **TikTok** | Account handle, hashtag, video URL, or search term | Videos and their comments. | #### News | Platform | Identifier | Notes | | --------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | **Google News** | Search terms | Multi-language search supported (English, French, Spanish, German, Italian, Portuguese, Dutch, Japanese, Korean, Arabic, Chinese). | #### AI assistants The same wizard can also query **Claude, ChatGPT, Gemini, Perplexity, Grok, DeepSeek, and Mistral** about your brand. That's a separate source type with its own analytics: see [AI Visibility](/boundaryai-docs/bringing-in-your-feedback/ai-visibility.md). {% hint style="info" %} **Don't see your source?** Drop us a line via the in-app upgrade prompt. Additional sources can be wired into the same flow. {% endhint %} *** ### Plan availability and credits Web scraping is a **Standard plan or above** feature. On Starter, the agent management page shows the catalogue but the *Run* action is replaced with an upgrade prompt. Agents are metered separately from the rest of the platform: * **Web & Social Media Credits** are a dedicated balance (independent of the Usage Allowance that runs surveys and analyses). You see the remaining balance from the Integrations Hub → *Web & Social Media Credits* section. * Each run **deducts credits up front** based on the intensity tier you choose (see below). * If a run **fails** before producing data, credits are **refunded automatically**. * You can **top up** in fixed packages (25 / 50 / 100 / 250 / 500 / 1,000 credits) via Stripe checkout, or rely on a monthly allocation included with your plan. * A full **credit history** is available from the same section, with one row per top-up, run, and refund. Plan and balance are checked before every run. If you do not have enough credits, the run does not start and no charge is made. *** ### Creating an agent The agent wizard is designed around what you actually want to watch, not the technical configuration. The ideal flow is: describe your goal → BAI Analytics suggests the right platforms and identifiers → you confirm or adjust. #### Step 0: Tell BAI Analytics what you want When you click **New Agent**, the first screen is a single text box. Describe what you want to track, in plain language. Examples: * *"Reviews and reactions about Hotel Nimbus across major travel sites and Twitter."* * *"Public discussions of Acme CRM on Reddit, X, and tech news."* * *"Customer feedback on our new restaurant in Barcelona: Google, TripAdvisor, and TikTok."* BAI Analytics parses the prompt, suggests **which platforms make sense for the goal**, and pre-fills URLs, handles, or search terms where it can. {% hint style="success" %} **Tip.** A specific prompt that names the brand, product, or place produces stronger autofills than a generic one. *"Customer feedback"* gives the AI no anchor; *"Customer feedback on the BAI Analytics dashboard"* lets it suggest concrete handles and queries. {% endhint %} #### Step 1: Sources The Sources step shows every supported platform, **grouped by how much input you need to give**: * **Auto**: Reddit, X, Google News, TikTok. You provide search terms, hashtags, handles, or URLs; BAI Analytics handles the rest. * **AI-assist**: Google Reviews, Trustpilot, TripAdvisor, Avis Vérifiés, Instagram, LinkedIn, Facebook. You provide a name or URL; the AI helps locate the right page if needed. * **Manual**: YouTube. You provide explicit video or channel URLs. * **AI assistants**: Claude, ChatGPT, Gemini, Perplexity, Grok, DeepSeek, Mistral. Selecting these switches the wizard to the brand-first [AI Visibility](/boundaryai-docs/bringing-in-your-feedback/ai-visibility.md) flow. For each platform you enable, an **Add source** input lets you paste URLs, handles, or keywords. Inputs become validated chips on Enter, comma, or paste, so you can drop in a list of ten URLs at once and get instant feedback on which ones the platform recognised. A small progress counter on each group ("2 of 3 ready") tells you when you have enough sources to proceed. {% hint style="info" %} **One agent, many platforms.** A single agent can watch any combination of platforms simultaneously. There's no need to create one agent per source. {% endhint %} #### Step 2: Behaviour Once your sources are in, the second step covers how the agent behaves: * **Agent name and description**: what shows up on the agent card and in the destination Feedback Group. * **Topic**: short label used in analytics views. * **Intensity**: *Standard*, *High*, *Extra high*, or *Custom*. See Intensity tiers below. * **Schedule**: choose **Run Once**, **Scheduled**, or **Ongoing**. For **Scheduled** and **Ongoing**, set **Frequency**, the time in **UTC**, and the day of week or day of month when needed. * **Timeframe**: optional date range to scope a backfill on the first run. * **Analysis language**: sets the source language for sentiment, theming, and translation. Defaults to your browser's language. Save the agent and BAI Analytics lands it inside the Feedback Group you created it in, or inside *Individual Surveys* if no group was selected. The agent appears as a card with platform badges, last-execution status, and a **Run** button. *** ### Intensity tiers Intensity controls how much data a single run pulls. Higher tiers cost more credits but go deeper across all selected platforms. | Tier | Items per platform | Comments per post | Credits (minimum per run) | | -------------- | ------------------ | ----------------- | ----------------------------- | | **Standard** | 250 | 10 | 5 | | **High** | 2,500 | 20 | 25 | | **Extra high** | 5,000 | 50 | 75 | | **Custom** | up to platform max | configurable | calculated from your settings | Each platform has its own maximum, and *Custom* is bounded by those limits. You don't need to memorise them: the form caps your input automatically when you save. {% hint style="success" %} **Pick Standard for first runs.** If a Standard run already returns the breadth of feedback you need, you have no reason to pay for High. If you see "more available" indicators in the analysis, scale up. {% endhint %} *** ### Per-source parameters Each platform exposes a small number of platform-specific options that the wizard surfaces when relevant: * **Reddit**: subreddits, sort (new / hot / top / relevance / comments), post type (link / self / all), minimum score, max comments per post. * **X (Twitter)**: hashtags, account handles, max tweets. * **Google Reviews / Trustpilot / TripAdvisor**: list of place / company / listing URLs, minimum star rating, max reviews. * **Instagram / Facebook / LinkedIn**: list of profile or page URLs. * **YouTube**: video URLs, or channel URLs (up to 10) to pull every video in a timeframe. * **TikTok**: account handles, hashtags, video URLs, or search terms. * **Avis Vérifiés**: company review-page URL. * **Google News**: search terms; multi-language search across 11 languages. The wizard validates each input against platform-specific rules. For example, Trustpilot URLs must follow `trustpilot./review/` and TripAdvisor URLs are anchored to `tripadvisor.com` and its regional variants to prevent typo-driven mismatches. *** ### Running an agent #### Choosing how often an agent runs When you set up an agent, the **Schedule** step asks **"How often should this run?"** You have three choices: * **Run Once**: **Collect feedback on demand.** * **Scheduled**: **Run automatically on a schedule.** * **Ongoing**: **Run automatically on a recurring schedule; only new data is scraped each run.** For **Scheduled** and **Ongoing** agents, pick a **Frequency** (**Daily**, **Weekly**, **Monthly**, or **Every 3 months**) and the time of day in **UTC**. For **Weekly**, also choose a day of week. For **Monthly** and **Every 3 months**, choose a day of month. The agent card then shows **Next: …**. {% hint style="info" %} **Tracked groups default to Ongoing.** When you create an agent from a Feedback Group that tracks feedback over time (Evolution), the wizard pre-selects **Ongoing**, weekly, with a seven-day first look-back, since continuous collection is the point of a tracked group. You can still switch to Run Once. {% endhint %} #### First run vs later runs The look-back window you choose when creating an agent (**Last 7 / 30 / 90 days**, **Last 1 Year**, **All Time**, or a custom range) applies to the **first run only**. After that, each **Scheduled** or **Ongoing** run collects only the **new data since the previous run**, so you do not pay to re-scrape the same posts. For **Ongoing** agents, a custom look-back is a single **start date** rather than a closed range: the first run reaches back to that date, and every later run just picks up what's new, so no end date exists. The agent card shows an open-ended look-back as *Since {date}*. Only **Run Once** agents need a start **and** end date. #### Where a re-run's data goes If you manually re-run an agent that already has a source in the Feedback Group, you're asked **"Where should the new data go?"**: * **Add to existing source** — merge the new items into the same source. * **Overwrite existing source** — replace what's there with this run's results. * **Create a new source** — keep this run as a separate source alongside the old one. Sources feeding an evolution-tracked group skip this choice: they're always append-only, since evolution needs every period's data kept intact. #### Keeping ongoing agents running with Auto top-up The agent wizard includes an **Auto top-up** option: > Automatically add credits so an ongoing agent never pauses. Scheduled and ongoing agents pause if your **Web & Social Media Credits** run out. Turn on **Auto top-up** to add credits automatically when your balance drops below a threshold you set. Auto top-up needs a saved payment method and is available on paid plans only. If a scheduled run cannot secure enough credits, the run card shows **Scheduled run did not start**. The reason explains what blocked the run. Possible messages are: * *Insufficient credits, top up to resume.* * *Auto top-up was attempted but credits are still insufficient.* * *No payment method on file for auto top-up.* * *Auto top-up failed. Please verify your card.* #### Real-time progress Once a run starts, a progress card shows: * A **percentage bar** for the overall run. * The **current platform** being scraped and the items collected so far. * A **per-platform status grid**: checkmarks for completed platforms, spinners for in-progress, an X for any that errored. * Any **error messages** with a platform-specific code. You can keep working in another tab; progress is tracked centrally and the toast follows you. #### Stuck and failed runs A run that stalls is automatically marked as failed so you can start a fresh one. Credits deducted at the start of a failed run are refunded automatically. #### Cancelling Click **Cancel** on the agent card during a run to stop it early. Already-scraped data is kept; in-progress platforms are aborted cleanly. #### Retrying If a run fails or partially fails (e.g. one platform errored while two succeeded), the execution history offers a one-click **Retry**. *** ### What scraped data looks like in a Feedback Group Each scraped item (a review, a tweet, a comment, a news mention) becomes a structured response in the destination Feedback Group, mapped as follows: | Field | Source | Used for | | ---------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- | | **Response** *(Long Answer)* | The main body text (review, tweet, comment) | Theme detection, sentiment, AI analysis. | | **Source** *(Metadata)* | The platform name (e.g. *Google Reviews*) | Segmentation: filter analyses by platform. | | **URL** *(Metadata)* | Direct link to the original post | Click-through from the analysis to the source. | | **Rating** *(Metadata)* | 1 – 5 star rating | Review-site sentiment cross-check; used in the rating-distribution chart. | | **Likes** *(Metadata)* | Engagement count | X / Twitter only; available as a segmentation dimension. | Because everything ends up as standard answers, scraped data participates fully in **Grouped Themes (previously called Super-Themes)** at the Feedback Group level, can be **filtered by date or sentiment** in the analysis view, and can be **rolled into reports** alongside survey responses and connector tickets. Monitoring is not configured in the agent wizard: the group's monitors with **Auto-cover new sources** on watch new agent sources automatically, and the wizard shows which ones will apply. See [Custom Monitoring](/boundaryai-docs/analysing-your-feedback/custom-monitoring.md). #### The Data Source card On the qualitative overview of an agent's source, a *Data Source* card surfaces: * A **platform breakdown** with per-platform item counts. * A **rating-distribution chart** (1 – 5 stars) for review platforms, a quick visual on overall sentiment from review sites. * The **last collected** date. * A **failed-platforms warning banner** if any platform errored on the most recent run, with the list of which ones. * Direct links to **Manage agents** and **Raw data**. *** ### Managing agents Each agent's card shows a running total: the full count of items collected across every run to date, not just the most recent one, so you can see a source's overall size at a glance. Each agent appears as a card on the Agents page with quick actions: * **Run**: start a new execution; intensity selector pops up first. * **Edit**: re-open the wizard with the agent's saved configuration. Intensity is auto-detected from the saved limits, so a custom-tuned agent doesn't lose its settings on edit. * **Cancel**: stop an in-flight run. * **Save as template**: see Templates below. * **Delete**: permanently remove the agent. * **Pause / Resume**: toggle whether the agent is active, without losing its configuration. The card updates automatically while a run is live, so you can watch progress without refreshing. #### Execution history Every agent has an **execution history** view with: * One row per run, showing started time, items collected, items imported (after dedup), status, and a brief error summary if any. * A **per-platform breakdown** for each run: which platforms succeeded, which failed, item counts for each. * A **Retry** button on failed or partially-failed runs that re-uses the same configuration. This is where you go to investigate "why did fewer items come in this week" or "why did Trustpilot stop returning data" without leaving BAI Analytics. *** ### Templates If you build an agent configuration that works well (say, a multi-platform brand-listening setup) you can save it as a **template** with the star icon on the agent card. Templates: * Become **clonable** within your organisation, so a teammate can spin up a similar agent in seconds. * Are version-independent. Editing the original agent does not retroactively change clones. * Are useful for **standard playbooks** (event-monitoring, product-launch listening, competitor tracking) you expect to re-run. Templates appear at the top of the New Agent flow alongside the natural-language prompt, so anyone in the org can start from a vetted setup. *** ### Platform-status modal A small **Platform status** modal accessible from the Agents page shows a real-time health check for every supported platform: how many of its underlying collectors are operational, how many succeeded vs total runs in the last 48 hours. Use it to diagnose whether a poor run was your configuration or a temporary platform-side issue. A *Refresh* button bypasses the cached status and forces a fresh check. *** ### How agents differ from connectors and uploads | Feature | Use it for | Auth | Cadence | | ---------------------- | ----------------------------------------------------------- | --------------------- | -------------------------------- | | **Agents (this page)** | Public data: reviews, social posts, news | None (web automation) | On demand, Scheduled, or Ongoing | | **Connectors** | Data inside tools you own: support, dev, project-management | Secure sign-in | Continuous (30-min) | | **Uploads** | Historical or third-party exports | None | One-shot | | **Surveys** | Direct outreach to known respondents | Optional passcode | On respondent submission | You can mix all four inside a single Feedback Group, and BAI Analytics' analytics treat them uniformly. *** ### Best practices * **Start with a focused prompt.** *"Brand sentiment for X across major review sites and Twitter"* yields a tighter, more useful agent than *"Customer feedback."* * **Pick the right intensity for the cadence.** A weekly Standard run on a small brand is usually enough; a daily Standard run on a large brand may miss data. Go High instead. * **Use a dedicated Feedback Group per topic.** Don't mix brand listening with employee feedback in the same group; the Grouped Themes will be muddled. * **Validate sources after the first run.** The platform-status modal and the execution-history view tell you which platforms are returning data. If one platform is consistently empty, double-check the URL or handle. * **Treat *****Custom***** intensity as the exception, not the default.** The three preset tiers cover most use cases; *Custom* is for power users who know exactly which platform-specific limit they want to push. * **Save proven setups as templates.** A team running brand listening across multiple products will build the same configuration repeatedly. Templates remove the re-work. * **Refund-aware retries.** Failed runs refund credits, so re-running a failed agent is safe. You won't be double-charged.