> For the complete documentation index, see [llms.txt](https://documentation.proto.cx/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.proto.cx/docs/modules/perception.md).

# Perception

Monitor public sentiment about your organisation across the web.

{% hint style="info" %}
Perception monitors public mentions of your organisation across social media, news sites, and app stores — scraped, categorised, and scored for sentiment.
{% endhint %}

{% hint style="warning" %}
Requires the **View perception** permission to open Perception. Adding, editing, or deleting sources and keyword groups additionally requires **Manage perception** — without it, the Sources and Keywords tabs are visible but read-only.
{% endhint %}

{% hint style="warning" %}
Perception is in early release. **Data**, **Sources**, and **Keywords** are available; **Raw Data**, **Alerts**, and **Categorization** are not yet released.
{% endhint %}

Open Perception from the eye icon in the left navigation.

***

## Date range

Click the **Date range** chip to open the date picker. See [Interactions — Date range](/docs/modules/analytics/interactions.md) for full details of the date picker and presets. All data is shown in your workspace timezone.

***

## Summary tiles

| Metric                | What it shows                                            |
| --------------------- | -------------------------------------------------------- |
| Total scraped entries | All mentions collected across every source in the period |
| Social media posts    | Count and % of entries from social platforms             |
| News site mentions    | Count and % of entries from news sites                   |
| App store reviews     | Count and % of entries from app store reviews            |

***

## Top mentions

Three tables summarise what's being said, each broken down by source:

| Table                        | Columns                  |
| ---------------------------- | ------------------------ |
| **Top mentioned keywords**   | Source, Keyword, Count   |
| **Top mentioned categories** | Source, Category, Count  |
| **Top sentiment**            | Source, Sentiment, Count |

***

## Data breakdown

A chart of scraped entry volume over the selected period.

| Control      | Options                                           |
| ------------ | ------------------------------------------------- |
| Group by     | Hour, Day, Week, Month, Quarter, Year             |
| Segment by   | Dimension to split the chart by                   |
| Display mode | Actual or relative values                         |
| Source       | Filter to specific sources                        |
| Source type  | Filter to social media, news sites, or app stores |
| Sentiment    | Filter by sentiment score                         |
| Keywords     | Filter by specific keywords                       |

Select **Reset all** to clear filters.

***

## Side-by-side comparison

Two additional charts beneath Data breakdown, each independently configurable with the same Group by, Segment by, Display mode, Source, Source type, Sentiment, and Keywords controls — useful for comparing two cuts of the data at a glance.

***

## Sources

{% hint style="info" %}
Without the **Manage perception** permission, the Sources tab restricts editing: the add-source button, and each source's **Recurring** switch and **Delete** action in the list, are disabled. A source's detail panel still opens, but every field and action in it — name, keyword groups, recurring scraping, scrape manually, and retry — is disabled too.
{% endhint %}

Sources are the pages, profiles, and keyword searches that Perception scrapes on a schedule or on demand, grouped by platform. **Facebook** and **X (Twitter)** sources can currently be created and scraped. Other platforms (Instagram, TikTok, YouTube, App Store, Play Store, and News) are listed but not yet supported — attempting to create a source for an unsupported platform is rejected with "Scraping is not supported for this platform yet."

### Adding a source

Choose a platform and a method:

| Method        | What it scrapes                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| Page-based    | Facebook: posts and comments from a single page. X (Twitter): posts from a single profile — replies are not scraped. |
| Keyword-based | Public posts matching one or more keyword groups                                                                     |

| Field                              | Description                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source name                        | Required label shown in the sources list                                                                                                                                                                                                                                                                                                                                                                      |
| Page/profile URL (page-based only) | Facebook: a facebook.com page URL. X: a profile URL on x.com or twitter.com (optionally prefixed with [www](http://www). or mobile.) pointing at exactly one handle, e.g. `https://x.com/handle`. Links to X pages such as home, explore, search, notifications, messages, settings, or an individual post are rejected as "Invalid X (Twitter) profile URL.", as is any URL with more than one path segment. |
| Keywords (keyword-based only)      | One or more custom or team keyword groups to search for; at least one is required. A keyword group can be linked to at most one keyword-based source per platform, so the same group can be used by a Facebook keyword source and an X keyword source at the same time, but not by two Facebook sources.                                                                                                      |
| Recurring scraping                 | Toggle to run scraping automatically, with an interval of 1–30 days, 1–720 hours, or 10–720 minutes                                                                                                                                                                                                                                                                                                           |
| Historical scraping                | Optional one-off backfill over a date range of up to one year, no earlier than 1 January 2024                                                                                                                                                                                                                                                                                                                 |

Facebook's keyword search only filters by whole UTC day, so historical and manual scrape ranges for Facebook keyword-based sources are day-only (no time of day). X sources — page-based and keyword-based alike — filter down to the second, so their ranges can include a specific time of day.

For a keyword-based source, if none of the selected keyword groups produce a usable search query (for example, a group whose only text is punctuation), the scrape run fails rather than being sent to the source's platform.

### Sources list

| Column                 | Description                                                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Type                   | Page or Keyword                                                                                                    |
| Name                   | The source's name                                                                                                  |
| Scope                  | The page/profile URL (page-based) or the linked keyword group names (keyword-based)                                |
| Recurring              | Switch to turn recurring scraping on or off directly from the list; reverts and shows an error if the change fails |
| Auto scraping status   | Status of the most recent recurring scrape                                                                         |
| Manual scraping status | Status of the most recent manual scrape                                                                            |

Selecting a row opens its detail panel. The row's actions menu offers **Delete**, which permanently removes the source and its scrape configuration once confirmed.

### Editing a source

The detail panel lets you rename the source, change its keyword groups (keyword-based sources only), adjust recurring scraping, and start a manual scrape for a custom date range.

Changing the recurring interval from the detail panel is validated against the same bounds as creating a source — 1–30 days, 1–720 hours, or 10–720 minutes — and a value outside these bounds is rejected the same way.

Recurring scraping can also pause itself automatically: if all of a keyword-based source's keyword groups become disabled or are removed, leaving no active keywords to search, Perception turns off recurring scraping for that source and records a "Recurring scraping auto-paused" event in its log. This applies to keyword-based sources on any supported platform.

Turning recurring scraping on — at creation, by switching it back on, or by changing the interval — schedules the next run for the current time plus the interval. That run's date range covers from the current time up to the newly scheduled time.

Once a recurring run executes, Perception immediately schedules the following run the same way, but measured from that run's own scheduled time rather than from when it actually ran. Each run's date range therefore always starts exactly where the previous run's schedule left off, so scraped windows stay contiguous even if a run starts late — with no gap or overlap, whatever the interval unit. The source's timezone setting is not used for these automatic ranges; it only affects date validation for manual and historical scrapes.

### Scraping logs

Each source's detail panel lists its history. A scrape run's results breakdown depends on the source's platform and method:

| Source                  | Breakdown shown                                                       |
| ----------------------- | --------------------------------------------------------------------- |
| Facebook, page-based    | One row each for Posts and Comments                                   |
| Facebook, keyword-based | One row per keyword group                                             |
| X, page-based           | One row for Posts — X does not have a separate replies/comments phase |
| X, keyword-based        | One row per keyword group                                             |

Each row shows new and duplicate entry counts. The log also includes:

| Entry                                 | Details shown                                                                                                                           |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Scrape run                            | Trigger (recurring or manual), status (scheduled, in progress, success, or failed), and date range scraped. Failed runs can be retried. |
| Recurring scraping enabled / disabled | Who made the change                                                                                                                     |
| Recurring interval updated            | The new interval and who made the change                                                                                                |
| Recurring scraping auto-paused        | Logged automatically when a keyword-based source runs out of active keywords; not attributed to a user                                  |

***

## Keywords

{% hint style="info" %}
Without the **Manage perception** permission, the Keywords tab restricts editing: the **Use custom keywords** and **Use team keywords** toggles, **Add keyword group**, and each keyword group's **Enable** switch are disabled, and bulk selection of keyword groups is unavailable.
{% endhint %}

Custom and team keyword groups managed on the Keywords tab can be linked to keyword-based sources on the Sources tab. Disabling a custom keyword group, or excluding a team from keywords, while it is linked to one or more sources prompts a confirmation first, since the change affects those sources' scraping:

| Action                                          | Effect once confirmed                                                                                    |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Disable a custom keyword group / exclude a team | Linked sources stop searching for it; it is dropped from each linked source on that source's next scrape |
| Last active keyword removed from a source       | The source's recurring scraping is automatically paused                                                  |

The confirmation also applies to bulk disabling — for a "select all matching" bulk action, the number of affected sources cannot be shown in advance, so confirmation is always required in that case.

Deleting a [team](/docs/settings/general/teams.md) has the same effect on any source that team's keyword group is linked to, but without a confirmation prompt, since the deletion happens from Team settings rather than this tab: the group stops being searched, and it no longer appears in the linked source's Scope.