# AGENTS
Source: https://docs.threadlytics.io/AGENTS



> **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project.
> For Mintlify product knowledge (components, configuration, writing standards),
> install the Mintlify skill: `npx skills add https://mintlify.com/docs`

# Documentation project instructions

## About this project

* This is a documentation site built on [Mintlify](https://mintlify.com)
* Pages are MDX files with YAML frontmatter
* Configuration lives in `docs.json`
* Run `mint dev` to preview locally
* Run `mint broken-links` to check links

## Terminology

## Style preferences

* Use active voice and second person ("you")
* Keep sentences concise — one idea per sentence
* Use sentence case for headings
* Bold for UI elements: Click **Settings**
* Code formatting for file names, commands, paths, and code references

## Content boundaries


# How to import and export keywords
Source: https://docs.threadlytics.io/import-export-keywords

Export your Keyword Monitor settings to a CSV file or add multiple keywords at once with a CSV import.

# Import and export keywords

Use **Export CSV** to download your current keyword setup, or **Import CSV** to add multiple keywords at once. Importing is useful when you are setting up a new account, adding a list of competitors, or moving keyword settings between workspaces.

<Note>
  Imports create new keywords only. They do not update or delete existing keywords.
</Note>

## Who can use it

* All users with access to the Keywords page can export keywords.
* Only **Admin** users can import keywords.

## Export keywords

1. Open **Keywords** from the sidebar.
2. Click **Export CSV** at the top of the page.
3. Threadlytics downloads a file named `keywords-YYYY-MM-DD.csv`.

The exported CSV includes each keyword and its saved monitoring settings:

* Keyword term and type
* Tags
* Related keywords
* Context keywords
* Negative keywords
* Target subreddits
* Active or inactive status

Exporting is a good way to create a correctly formatted import template. You can edit the exported file in Excel, Google Sheets, or another spreadsheet tool, then import it again.

<Warning>
  The CSV export covers the main keywords on the Keywords page. It does not include Global Context Keyword collections or Global Negative Keyword collections.
</Warning>

## Import keywords

1. Open **Keywords**.
2. Click **Import CSV** in the upper-right corner.
3. Choose a `.csv` file from your computer.
4. Review the **Import Results** window.

The results show:

* **Rows processed**. The number of rows read from the file
* **Created**. The number of new keywords added
* **Skipped**. Rows that could not be added
* **Row-level reasons**. Details such as a missing term, duplicate keyword, or plan limit

After the import, click **Refresh** to begin collecting the latest Reddit results for your newly added keywords.

## CSV format

Your CSV must include a header row. Use these column names exactly:

```csv theme={null}
term,type,tags,contextKeywords,negativeKeywords,relatedKeywords,targetSubreddits,isActive
```

Only `term` is required. The other columns are optional.

| Column             | Required | What to enter                                                                                      |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------- |
| `term`             | Yes      | The word, phrase, brand, or topic you want to monitor.                                             |
| `type`             | No       | `brand`, `competitor`, or `industry`. If blank or not recognized, the keyword is added as `brand`. |
| `tags`             | No       | Labels for organizing keywords.                                                                    |
| `contextKeywords`  | No       | Words that must appear with the main keyword for a mention to be relevant.                         |
| `negativeKeywords` | No       | Words that exclude a post from results.                                                            |
| `relatedKeywords`  | No       | Alternative names, spellings, or related terms to monitor alongside the main keyword.              |
| `targetSubreddits` | No       | Specific subreddits to monitor. Leave blank to monitor across Reddit.                              |
| `isActive`         | No       | `true` or `false`. Leave blank to add the keyword as active.                                       |

### Add multiple values in one field

For any list field (such as tags, context keywords, or target subreddits) separate values with a semicolon (`;`).

**For example:**

```csv theme={null}
term,type,tags,contextKeywords,negativeKeywords,relatedKeywords,targetSubreddits,isActive
Acme,brand,priority;enterprise,security;compliance,jobs;hiring,Acme Inc;Acme Cloud,soc2;cybersecurity,true
Competitor One,competitor,competitive,,jobs,CompetitorOne,saas;startups,true
GRC,industry,category,compliance;security,job;career,governance risk compliance,ciso;grc,false
```

For `targetSubreddits`, enter the subreddit name without `r/`, such as `cybersecurity` or `soc2`.

<Tip>
  If a value contains a comma, wrap the full CSV cell in double quotes. For example: `"governance, risk, and compliance"`.
</Tip>

## What happens during an import

Threadlytics checks each row independently. A problem with one row will not stop other valid rows from importing.

### Duplicate keywords

Threadlytics skips a keyword if the same term already exists in the selected workspace. Duplicate checks ignore capitalization, so `Acme`, `ACME`, and `acme` are treated as the same keyword.

### Missing keyword terms

Rows without a value in the `term` column are skipped.

### Keyword limits

Your subscription's keyword limit still applies during an import. If importing additional rows would exceed your limit, Threadlytics imports the rows that fit and skips the rest. The Import Results window will show that the limit was reached.

### Active and inactive keywords

Keywords are active by default. Use `false` in the `isActive` column when you want to save a keyword without monitoring it right away. You can activate it later from Keyword Monitor.

## Troubleshooting

### My file will not import

Make sure that:

* The file is saved as a `.csv` file.
* The first row contains the column headers.
* The header names use the exact spelling shown above.
* Each row has a value in the `term` column.
* List values are separated with semicolons, not additional CSV columns.

### Some keywords were skipped

Open the Import Results window to see the exact row number and reason. Common reasons are:

* The keyword already exists.
* The `term` field is blank.
* Your keyword limit has been reached.
* The row contains invalid data.

### I need to change existing keywords

Exporting and re-importing does not overwrite existing keywords. To change a keyword's type, filters, tags, or status, use the **Edit** action beside that keyword in Keyword Monitor.


# Cumulative Mentions
Source: https://docs.threadlytics.io/metrics/cumulative-mentions



## Overview

**Cumulative Mentions** is a running total of all Reddit posts and comments that match your tracked keywords, plotted over time. Each data point on the chart represents the total number of mentions found from the beginning of the selected time window up to that point.

Because the count never resets, this metric is useful for visualizing growth: a steeper slope means faster discovery of new mentions, while a flat line means activity has slowed.

**Note:** If you've hit your plan mention cap (e.g., 5,000, 20,000, 100,000), older mentions may be missing, which would make the cumulative chart understated for earlier time periods.

## How Is It Calculated?

### Aggregation Logic

The chart buckets mentions into time periods based on the selected aggregation level, then adds each bucket's count to a running total:

```text theme={null}
cumulativeTotal[period] = cumulativeTotal[period - 1] + mentionsInThisPeriod
```

For example, if 50 mentions were found in week 1 and 30 in week 2, the chart plots 50 at week 1 and 80 at week 2.

### Aggregation Levels

| Level      | How Mentions Are Grouped                                |
| ---------- | ------------------------------------------------------- |
| **Days**   | Each data point = mentions found on that calendar day   |
| **Weeks**  | Each data point = mentions found in that 7-day window   |
| **Months** | Each data point = mentions found in that calendar month |

### Filters Applied Before Charting

The backend applies these filters before sending data to the chart:

* **2-year limit** – mentions older than 2 years are excluded
* **Client isolation** – only mentions belonging to the selected client's keywords are included
* **Target subreddit filter** – if a keyword has target subreddits configured, only mentions from those communities are counted
* **Keyword type filter** – optionally restrict to Brand, Competitor, or Industry keywords
* **Sentiment filter** – optionally restrict to positive, neutral, or negative mentions only
* **Specific keyword filter** – optionally show data for a single tracked term

### Duplicate Handling

A Reddit post that matches multiple keywords is counted only once per keyword it is linked to, preventing double-counting.

## Available Time Ranges

| Range    | Data Window    |
| -------- | -------------- |
| 7 days   | Last 7 days    |
| 14 days  | Last 14 days   |
| 30 days  | Last 30 days   |
| 90 days  | Last 90 days   |
| 180 days | Last 6 months  |
| 365 days | Last 12 months |

## Interpreting The Chart

| Pattern                   | What It Means                                                                  |
| ------------------------- | ------------------------------------------------------------------------------ |
| **Steep upward slope**    | New mentions are being discovered at a high rate                               |
| **Gradual, steady slope** | Consistent, stable discussion volume                                           |
| **Flat line**             | Little to no new activity in this period                                       |
| **Sudden step up**        | A spike event — a viral post, news story, or product launch driving discussion |

## Export

Click the export button on the chart to download the underlying data as a CSV file, including the date, period count, and cumulative total for each time bucket.


# Monthly Mentions
Source: https://docs.threadlytics.io/metrics/monthly-mentions



## Overview

**Monthly Mentions** shows the number of Reddit posts and comments matching your tracked keywords that were discovered in each individual calendar month. Unlike Cumulative Mentions, this metric does not carry forward. Each bar represents only the activity within that specific month, making it possible to compare performance month-over-month.

**Note:** If you've hit your plan mention cap (e.g., 5,000, 20,000, 100,000), older mentions may be missing. Months that pushed you over the limit may show fewer mentions than actually exist in Reddit.

## How Is It Calculated?

### Aggregation Logic

The chart aligns to calendar month boundaries. For each month in the selected time range:

1. The start and end of the month are calculated
2. All mentions with a `createdAt` timestamp falling within that window are counted
3. That count — and only that count — is plotted as the bar for the month

```text theme={null}
monthlyCount[month] = COUNT(mentions WHERE createdAt >= monthStart AND createdAt < monthEnd)
```

There is no carry-forward. If February had 200 mentions and March had 150, the bars show 200 and 150 respectively.

### Filters Applied Before Charting

The backend applies the same filters as the Cumulative Mentions chart:

* **2-year limit** – mentions older than 2 years are excluded
* **Client isolation** – only the selected client's keyword data is included
* **Target subreddit filter** – respects any subreddit restrictions configured per keyword
* **Keyword type filter** – optionally restrict to Brand, Competitor, or Industry
* **Sentiment filter** – optionally restrict to positive, neutral, or negative mentions
* **Specific keyword filter** – optionally isolate a single tracked term

## Available Time Ranges

The time range selector controls how many months are shown. The chart always aligns to the first of the month for the earliest period in the range:

| Range    | Months Shown       |
| -------- | ------------------ |
| 7 days   | Current month only |
| 30 days  | \~1 month          |
| 90 days  | \~3 months         |
| 180 days | \~6 months         |
| 365 days | \~12 months        |

## Interpreting The Chart

| Pattern                    | What It Means                                                                  |
| -------------------------- | ------------------------------------------------------------------------------ |
| **Consistently tall bars** | High, sustained mention volume month after month                               |
| **Growing bars over time** | Increasing brand awareness or discussion on Reddit                             |
| **Shrinking bars**         | Declining conversation volume — worth investigating                            |
| **One unusually tall bar** | A specific month had a viral moment, campaign launch, or news event            |
| **Very short bars**        | Low activity in that month — may reflect seasonal trends or gaps in monitoring |

## Difference From Cumulative Mentions

|                      | Monthly Mentions                  | Cumulative Mentions              |
| -------------------- | --------------------------------- | -------------------------------- |
| **Chart type**       | Bar chart                         | Area / line chart                |
| **Count resets**     | Yes — each month starts from 0    | No — totals keep growing         |
| **Best for**         | Comparing month-to-month changes  | Seeing overall growth trajectory |
| **Spike visibility** | Immediately obvious as a tall bar | Visible as a steeper slope       |

## Export

Click the export button on the chart to download the monthly data as a CSV file, including the month label and mention count for each bar.


# Sentiment
Source: https://docs.threadlytics.io/metrics/sentiment



## Overview

**Sentiment** classifies each Reddit mention as **Positive**, **Neutral**, or **Negative** based on the language used in the post or comment. This gives you a signal for how Reddit users feel about a topic, not just how often it is being discussed.

## Where It Appears

* **Dashboard** – Sentiment donut chart and Brand Sentiment summary card
* **Sentiment Analysis page** – full breakdown by keyword
* **Conversations page** – per-mention sentiment label and filter
* **Keywords page** – sentiment percentage column per keyword
* **Top Sources page** – average sentiment per user

## How Is It Calculated?

Sentiment is determined by a custom keyword-based engine that runs automatically when a mention is saved.

### Step 1: Normalize the Text

The mention's title and body are combined and converted to lowercase so that "Amazing" and "amazing" are treated identically.

### Step 2: Count Signal Words

The engine scans the normalized text and counts occurrences of words from three predefined signal lists:

| Signal Type            | Example Words                                                                                                               |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Positive**           | amazing, awesome, excellent, fantastic, great, good, love, perfect, wonderful, effective, useful, helpful, easy             |
| **Negative**           | terrible, awful, horrible, bad, worst, hate, disgusting, disappointing, frustrated, useless, broken, bug, error, slow, poor |
| **Question / Neutral** | what, how, why, can, should, suggest, advice, opinion — plus every `?` character in the text                                |

### Step 3: Calculate Ratios

```text theme={null}
totalScore    = positiveCount + negativeCount + questionCount
positiveRatio = positiveCount / totalScore
negativeRatio = negativeCount / totalScore
questionRatio = questionCount / totalScore
```

### Step 4: Classify

The final classification is determined by comparing the ratios:

| Condition                                                              | Classification                     |
| ---------------------------------------------------------------------- | ---------------------------------- |
| `totalScore` is 0 (no signal words found)                              | **Neutral**                        |
| `questionRatio > 0.4` and `positiveRatio == negativeRatio`             | **Neutral**                        |
| Neither positive nor negative ratio exceeds 0.3, or they are too close | **Neutral**                        |
| `positiveRatio > negativeRatio` AND `positiveRatio > 0.3`              | **Positive**                       |
| `negativeRatio > positiveRatio` AND `negativeRatio > 0.3`              | **Negative**                       |
| `questionRatio > 0.4` and `positiveRatio > negativeRatio`              | **Positive** (fixed score of 0.3)  |
| `questionRatio > 0.4` and `negativeRatio > positiveRatio`              | **Negative** (fixed score of -0.3) |

The engine intentionally biases toward **Neutral** when question language dominates. A post asking "What do people think of this tool?" contains positive and negative words but is fundamentally an inquiry, not an opinion. So it is classified as Neutral or weakly positive/negative rather than strongly either way.

### Sentiment Score

In addition to the label, a numeric score is stored ranging from -1.0 to +1.0:

* **Positive score:** `min(positiveRatio - negativeRatio, 1.0)`
* **Negative score:** `max(-(negativeRatio - positiveRatio), -1.0)`
* **Question-dominant score:** capped at ±0.3

This score is used elsewhere in the platform, including opportunity scoring.

## How Sentiment Feeds Opportunity Score

Sentiment is one input into the Opportunity Score (0–100) that rates how worth engaging with a post is:

| Sentiment | Points Added to Opportunity Score |
| --------- | --------------------------------- |
| Positive  | +10 points                        |
| Neutral   | +5 points                         |
| Negative  | 0 points                          |

Other factors (upvotes, comment count) also contribute to the opportunity score.

## Sentiment Aggregates

When sentiment is shown at the keyword or organization level, it is calculated as:

```text theme={null}
positiveMentions / totalMentions × 100 = positive sentiment %
```

This percentage is what appears in the Keywords table's Sentiment column and the Dashboard's Brand Sentiment card.

## Limitations

* The engine relies on a fixed vocabulary of signal words. Slang, sarcasm, and highly domain-specific language may be misclassified
* Very short posts with few words may default to Neutral due to a low `totalScore`
* Sentiment is assigned at index time and is not automatically recalculated if the signal word lists are updated. A keyword reset and re-refresh is required to recompute sentiment for existing mentions.


# Share Of Voice
Source: https://docs.threadlytics.io/metrics/share-of-voice



## Overview

**Market Share of Voice** measures what percentage of the total Reddit conversation about a set of topics belongs to each brand or competitor you are tracking. It answers the question: "Of all the posts mentioning brands in this space, how many are about us versus our competitors?"

A higher Share of Voice indicates greater presence and visibility in Reddit discussions relative to the tracked competitive set.

## Where It Appears

* **Market Analysis page** – primary metric, shown as a pie chart, bar chart, and detailed table

## How Is It Calculated?

### What Is Included

Only keywords of type **Brand** and **Competitor** are included in the Share of Voice calculation. Industry keywords are excluded because they represent topics rather than specific entities competing for share.

### Share Percentage Formula

```text theme={null}
sharePercentage = (mentionsForKeyword / totalMentionsAcrossAllKeywords) × 100
```

For example, if Brand A has 400 mentions, Competitor B has 350, and Competitor C has 250 (total: 1,000), their shares of voice are 40%, 35%, and 25%, respectively.

### Trend Calculation

Each keyword also gets a trend indicator showing whether its share is growing or shrinking. This is calculated by comparing two consecutive 7-day windows:

```text theme={null}
recentCount   = mentions in the last 7 days
previousCount = mentions in the 8–14 days ago window

trendPercentage = ((recentCount - previousCount) / previousCount) × 100
```

| Trend Indicator | Condition                                                              |
| --------------- | ---------------------------------------------------------------------- |
| **Up ↑**        | `trendPercentage > 5%`, or `previousCount` was 0 and `recentCount > 0` |
| **Stable →**    | Change is within ±5%                                                   |
| **Down ↓**      | `trendPercentage < -5%`                                                |

## Optional Context Filter

The Share of Voice calculation supports an optional **context keyword** filter. When applied, only mentions that also contain one of the specified context terms are included in the calculation.

This allows for narrower competitive analysis. For example, you can calculate Share of Voice specifically within conversations about "running shoes" rather than across all mentions of the brands. This gives you a more relevant competitive picture for a specific topic or product category.

## "Others" Grouping

In the pie chart view on the Market Analysis page, keywords with a very small share of the total are automatically grouped into an **"Others"** slice. This keeps the chart readable when many competitors are tracked. The Detailed View tab always shows every keyword individually, regardless of size.

## Interpreting Share Of Voice

| Share Level | What It Suggests                                                           |
| ----------- | -------------------------------------------------------------------------- |
| **> 60%**   | Market leadership in Reddit conversations — strong brand visibility        |
| **30–60%**  | Competitive presence — monitoring competitors closely is valuable          |
| **\< 30%**  | Growth opportunity — competitors are dominating the conversation           |
| **Trend ↑** | Share is increasing — momentum is building                                 |
| **Trend ↓** | Share is declining — worth investigating what is driving competitor growth |


# Accounts
Source: https://docs.threadlytics.io/pages/accounts



## Overview

The Accounts page lets you monitor specific Reddit users — typically your own brand accounts, employee advocates, or competitor accounts you want to track. It surfaces karma trends, post/comment history, and flags any content that has been removed.

## Aggregate Statistics

Five summary cards at the top of the page give an org-wide view across all monitored accounts:

| Metric              | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| **Total Karma**     | Combined karma across all monitored accounts                       |
| **Total Posts**     | Total number of posts made by all tracked accounts                 |
| **Total Comments**  | Total number of comments made by all tracked accounts              |
| **Content Health**  | Percentage of posts and comments that are still live (not removed) |
| **Active Accounts** | Number of accounts currently being monitored                       |

## Monitored Accounts Table

A list of every Reddit account you are tracking.

### Table Columns

| Column           | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| **Username**     | Reddit handle — links directly to the user's Reddit profile          |
| **Display Name** | Optional friendly label you set when adding the account              |
| **Total Karma**  | Combined post and comment karma                                      |
| **Status**       | Current state: Active, Not Found, Suspended, Error, or Pending       |
| **Last Checked** | Timestamp of the most recent data refresh                            |
| **Actions**      | Refresh (re-fetch latest data) or Delete the account from monitoring |

## Adding an Account

Click **Add Account** to open the form. You only need to provide:

* **Reddit Username** – the account to monitor (without the u/ prefix)
* **Display Name** – optional label for your own reference

Once added, Threadlytics fetches the account's public data and begins tracking it.

## Account Details

Click any account in the table to expand a detailed view. This section is shown only when an account is selected.

### Stats Grid

| Stat              | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| **Total Karma**   | Combined karma with a trend indicator (↑ or ↓ vs. last check) |
| **Post Karma**    | Karma earned from submissions                                 |
| **Comment Karma** | Karma earned from comments                                    |
| **Removed Posts** | Count of posts that have been removed                         |

### Recent Posts

A table of the account's latest 10 posts:

* **Title** – post heading
* **Subreddit** – community where it was posted
* **Score** – current upvote count
* **Comments** – number of replies
* **Status** – **Live** or **Removed**

### Recent Comments

A table of the account's latest 10 comments:

* **Content** – snippet of the comment body
* **Subreddit** – community where it was posted
* **Score** – current upvote count
* **Status** – **Live** or **Removed**

The Removed status makes it easy to spot content that has been taken down by moderators, which may indicate account health issues or policy violations.


# Conversations
Source: https://docs.threadlytics.io/pages/conversations



## Overview

The Conversations page shows every Reddit post and comment that matches your tracked keywords. It is your primary workspace for reading, triaging, and engaging with relevant discussions. Each result is shown as a card with full post details, engagement metrics, and action controls.

## Quick Stats Bar

Three counters appear at the top of the page:

| Stat                  | What It Shows                                                      |
| --------------------- | ------------------------------------------------------------------ |
| **Total Mentions**    | Total posts and comments matched across all keywords               |
| **Currently Showing** | How many results are visible after applying your active filters    |
| **Opportunities**     | Mentions with a high opportunity score — posts worth engaging with |

## Conversation Cards

Each mention is displayed as a card containing:

* **Title and content** with your tracked keyword highlighted in the text
* **Subreddit** – clickable link to the community
* **Author** – Reddit username
* **Time posted**
* **Upvotes** and **comment count**
* **Sentiment** label (Positive / Neutral / Negative)
* **Opportunity score** (0–100%) indicating engagement potential
* **Matched context keywords** – which context terms were found in this post

### Card Actions

| Action                | What It Does                                                 |
| --------------------- | ------------------------------------------------------------ |
| **View on Reddit**    | Opens the original post in a new tab                         |
| **Mark as Engaged**   | Toggles the engaged status to track what you've responded to |
| **Save / Unsave**     | Bookmarks the conversation for later reference               |
| **Dismiss / Restore** | Hides the card from view; restorable via the Status filter   |
| **Add / Edit Notes**  | Attach notes to any conversation                             |

## Filters

Use the filter bar to narrow down results. All filters can be combined.

| Filter                 | Options                                                   |
| ---------------------- | --------------------------------------------------------- |
| **Search**             | Free-text search across titles, content, and authors      |
| **Keyword**            | Filter by one or more specific tracked keywords           |
| **Context Keywords**   | Show only mentions that matched specific context keywords |
| **Keyword Type**       | Brand, Competitor, or Industry                            |
| **Sentiment**          | Positive, Neutral, or Negative                            |
| **Opportunity Level**  | High, Medium, Low, Trending                               |
| **Status**             | New, Engaged, or Dismissed                                |
| **Saved**              | Show only bookmarked conversations                        |
| **Date Range**         | Custom start and end date picker                          |
| **Min / Max Comments** | Filter by engagement volume                               |
| **Min / Max Upvotes**  | Filter by post score                                      |
| **Subreddit**          | Limit results to a specific community                     |
| **Author**             | Filter by a specific Reddit username                      |

## Sorting

Click the sort control to order conversations by:

* **Recent** – newest first (default)
* **Most Comments** – highest engagement volume first
* **Opportunity** – highest opportunity score first

## Bulk Actions

Click **Select** to enter bulk mode. Use checkboxes (or Shift+Click for range selection) to select multiple conversations, then apply one of:

* **Mark as Engaged**
* **Save**
* **Dismiss**

## Manual Post Tracking

Use **Track Post** to manually add any Reddit URL to your conversations view. Useful for posts discovered outside of the automated monitoring. You can:

* Paste a Reddit post URL
* Associate it with one or more keywords
* Add an initial note

Once added, the post appears in your Conversations feed alongside automatically discovered mentions.


# Dashboard
Source: https://docs.threadlytics.io/pages/dashboard



## Overview

The **Dashboard** is the central hub of Threadlytics. It gives you an overview of your brand's Reddit presence, tracking mention volume, sentiment, engagement, and competitive positioning.

## Key Metrics (Summary Cards)

Four headline cards appear at the top of the page. Each card compares the current period against the previous week so you can instantly see whether things are trending up or down.

| Metric                  | What It Measures                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Brand Mentions**      | Total Reddit posts and comments that match your brand keywords (excludes competitor and industry keywords) |
| **Brand Sentiment**     | Percentage of brand mentions classified as positive                                                        |
| **Brand Opportunities** | High-quality posts worth engaging with, scored on upvotes, comment count, and sentiment                    |
| **Brand Engagement**    | Average engagement rate (upvotes + comments) across brand-related content                                  |

## Charts & Visualizations

### Cumulative Mentions Chart

An area/line chart showing the growth of total mentions over your selected time period. Useful for spotting long-term trends and sudden spikes.

* **Filters:** Time range (7, 14, 30, 90, 180, or 365 days), aggregation level (daily / weekly / monthly), keyword type, and sentiment
* **Export:** Download the underlying data as a CSV file

### Monthly Mentions Chart

A bar chart showing non-cumulative mention volume broken down by month. Good for comparing month-over-month performance.

* **Filters:** Same time range and keyword-type filters as the cumulative chart
* **Export:** CSV download available

### Brand vs. Competitor Chart

A multi-line chart overlaying the growth of your brand keywords against individual competitors. Shows up to 5 keywords per page, with pagination to cycle through more.

* **Color coding:** Each brand or competitor gets a distinct color
* **Time ranges:** Adjustable to match your other charts

### Brand Sentiment Chart

A donut/pie chart breaking down mentions into Positive (green), Negative (red), and Neutral (yellow) categories. Counts and percentages are listed below the chart for easy reading.

## Filters & Controls

* **Time range toggle:** Switch between 7, 14, 30, 90, 180, and 365-day windows
* **Keyword filter:** Narrow charts to specific tracked terms
* **Keyword type filter:** Show only Brand, Competitor, or Industry keyword data


# Keywords
Source: https://docs.threadlytics.io/pages/keywords



## Overview

The Keywords page is where you define and manage every term Threadlytics monitors on Reddit. It is divided into three sections: **Keyword Monitor** (your primary tracked terms), **Global Context Keywords** (must-include filters), and **Global Negative Keywords** (must-exclude filters).

## Keyword Monitor

This is the main section. Each keyword you add here triggers Reddit searches and accumulates mentions over time.

### Keyword Table Columns

| Column        | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| **Keyword**   | The term or phrase being tracked on Reddit                    |
| **Type**      | Classification: **Brand**, **Competitor**, or **Industry**    |
| **Tags**      | Optional metadata labels to help organize keywords            |
| **Status**    | Green dot = active (monitored); Grey dot = inactive (paused)  |
| **Mentions**  | Total unique Reddit posts and comments matched so far         |
| **Sentiment** | Percentage of mentions with positive sentiment (e.g., "+75%") |
| **Actions**   | Per-row dropdown for Edit, Refresh, Reset, and Delete         |

### Adding a Keyword

Click **Add Keyword** to open the creation form. Fields include:

* **Keyword** – the word or phrase to search for
* **Type** – Brand, Competitor, or Industry
* **Tags** – optional organizational labels
* **Related keywords** – alternative phrasings or synonyms
* **Context keywords** – additional terms that must also appear in a post for it to count (narrows results)
* **Negative keywords** – terms that disqualify a post (reduces noise)
* **Target subreddits** – restrict monitoring to specific communities

### Refresh & Sync

* **Refresh All** – triggers a full backend sync for all active keywords.
* **Individual Refresh** – refreshes only one keyword. A progress bar shows the current stage and estimated time remaining

### Bulk Actions

Select multiple keywords using the checkboxes (Shift+Click for range selection) to:

* **Activate** or **Deactivate** in bulk
* **Reset** – clears all gathered mentions for the selected keywords
* **Delete** – permanently removes the keywords and their data

### Usage & Limits

A usage indicator at the top shows how many keywords and mentions your plan allows (e.g., "5 / 10 keywords used"). Limits are enforced per plan tier.

### Role-Based Access

* **Admins** have full create, edit, refresh, and delete permissions
* **Members** see a read-only view — action buttons are visible but disabled, and a banner explains their access level

## Global Context Keywords

Context keyword collections act as reusable "must-include" filters. When a collection is applied to a keyword type, only mentions that contain at least one of the context terms will be kept.

| Field               | Description                                       |
| ------------------- | ------------------------------------------------- |
| **Collection Name** | A label for the group (e.g., "Purchase Intent")   |
| **Description**     | Optional notes on what the collection is for      |
| **Apply to Type**   | Brand, Competitor, Industry, or All keyword types |
| **Keywords**        | The list of terms that must appear in a mention   |

**Clean Up Existing Mentions** – re-evaluates all stored mentions against the current context rules and removes any that no longer qualify.

## Global Negative Keywords

Negative keyword collections act as reusable "must-exclude" filters. Any mention containing one of these terms is automatically discarded.

| Field               | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| **Collection Name** | A label for the group (e.g., "Job Listings Noise")                |
| **Description**     | Optional notes                                                    |
| **Apply to Type**   | Brand, Competitor, Industry, or All                               |
| **Keywords**        | Terms that disqualify a mention (e.g., "jobs", "gaming", "cheap") |

**Clean Up** – permanently deletes stored mentions that match the current negative keyword lists, keeping your data clean after you update the rules.


# Market Analysis
Source: https://docs.threadlytics.io/pages/market-analysis



## Overview

The Market Analysis page gives you a competitive view of how your brand compares to competitors across Reddit. It calculates Share of Voice, visualizes mention volume, and surfaces actionable insights based on the current data.

## Filters

| Filter              | Description                                                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Context Keyword** | Narrow all charts to mentions that contain specific conversation topics (pulled from your global context keyword collections) |
| **Date Range**      | Set a custom time window for all data on the page                                                                             |

## Market Share of Voice

The primary chart section shows how mentions are distributed across your brand and competitors.

### Views

Switch between three tabs:

**Share Distribution (Pie Chart)**

* Visualizes each keyword's percentage of total mentions as a slice of the pie
* Keywords with small mention counts are automatically grouped into an "Others" category to keep the chart readable

**Volume Comparison (Bar Chart)**

* Side-by-side bars showing raw mention counts per keyword
* Makes it easy to see absolute volume differences rather than percentages

**Detailed View (Table)**

* A full breakdown listing each keyword with its mention count, share percentage, and trend direction (↑ up / → stable / ↓ down)

## Key Insights

Three summary metrics appear alongside the charts:

| Metric              | What It Shows                                                      |
| ------------------- | ------------------------------------------------------------------ |
| **Share of Voice**  | Your brand's percentage of total mentions across all tracked terms |
| **Top Performer**   | The keyword with the highest mention count in the current period   |
| **Fastest Growing** | The keyword with the largest upward trend percentage               |

## Analysis Tips

An advice panel that generates recommendations based on your current data. Examples:

* **Market Leadership** – shown when your brand's share of voice exceeds 60%, with tips on maintaining dominance
* **Growth Opportunity** – shown when share falls below 30%, with suggestions for increasing visibility
* Other tips adjust dynamically as your data changes

## How Share of Voice Is Calculated

Share of voice is calculated as:

```text theme={null}
Brand Mentions ÷ Total Mentions (all tracked keywords) × 100
```

All keywords of type **Brand**, **Competitor**, and **Industry** contribute to the total. This gives you a proportional view of conversation ownership within the topics you're tracking.


# Sentiment
Source: https://docs.threadlytics.io/pages/sentiment-analysis



## Overview

The Sentiment Analysis page breaks down how Reddit users feel about your brand and competitors. It shows the overall sentiment distribution and provides a per-keyword breakdown so you can see exactly which terms are driving positive or negative conversation.

## Filters

| Filter           | Options                                   |
| ---------------- | ----------------------------------------- |
| **Keyword Type** | All Types, Brand only, or Competitor only |

## Brand Sentiment Analysis

A donut/pie chart showing the overall split of sentiment across all mentions that match the active filter.

**Sentiment categories:**

| Category     | Color         | Meaning                                                     |
| ------------ | ------------- | ----------------------------------------------------------- |
| **Positive** | Green         | Posts and comments with a favorable tone toward the keyword |
| **Neutral**  | Yellow / Grey | Informational or ambiguous content                          |
| **Negative** | Red           | Posts and comments with a critical or unfavorable tone      |

Below the chart, three stat cards display the raw mention count and percentage for each sentiment category.

## Sentiment by Keyword

A sortable table showing the sentiment breakdown for every individual tracked keyword that matches the current filter.

### Table Columns

| Column             | Description                                                                     |
| ------------------ | ------------------------------------------------------------------------------- |
| **Keyword**        | The tracked term, with a color-coded type badge (Brand / Competitor / Industry) |
| **Total Mentions** | Total number of Reddit posts and comments matched                               |
| **Positive**       | Count and percentage of positive mentions                                       |
| **Neutral**        | Count and percentage of neutral mentions                                        |
| **Negative**       | Count and percentage of negative mentions                                       |

Click any column header to sort the table by that metric. Sorting by **Negative %** quickly surfaces the keywords generating the most criticism.

## How Sentiment Is Determined

Threadlytics uses a simple keyword matching approach to analyze sentiment. Each mention is analyzed for the presence of positive and negative signal words within the content.

* **Positive:** words like *amazing, great, love, recommend, helpful*
* **Negative:** words like *terrible, bad, hate, bug, expensive, slow*
* **Neutral/Question:** words like *what, how, why, advice, opinion*

It counts matches, calculates ratios, and classifies as positive/negative/neutral. A sentiment **score** between -1 and +1 is also stored. The resulting score determines whether the post is classified as Positive, Neutral, or Negative.

It works well for clear-cut posts, but may misclassify sarcasm, complex opinions, or posts where the brand is mentioned alongside unrelated sentiment words.

This analysis runs automatically during keyword refresh and is stored alongside each mention.


# SERP Tracking
Source: https://docs.threadlytics.io/pages/serp-tracking



## Overview

The SERP Tracking page monitors where Reddit posts rank in Google search results for terms you care about. It records position history over time so you can see whether a Reddit thread is climbing or falling in search rankings.

## Tracked Posts Table

A list of every Reddit post you are currently monitoring in Google search results.

### Table Columns

| Column          | Description                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| **Keyword**     | The Google search query being tracked (e.g., "best project management tool") |
| **Position**    | Current rank in search results (e.g., #3)                                    |
| **Result Type** | How the result appears (e.g., organic, sitelink)                             |
| **Change**      | Trend since the last check — improved (↑), declined (↓), or stable (→)       |
| **Device**      | Whether the ranking is tracked for Desktop or Mobile search                  |
| **Location**    | Target country for the search (e.g., United States)                          |
| **URL**         | Link to the Reddit post being tracked                                        |
| **Actions**     | View ranking history or Delete the tracked post                              |

## Tracking a New Post

Click **Track New Post** to open the form. Fill in:

| Field                  | Description                                             |
| ---------------------- | ------------------------------------------------------- |
| **Reddit Post URL**    | The full URL of the Reddit thread to monitor            |
| **Google Search Term** | The keyword or phrase to search for in Google           |
| **Country**            | Target country for search results (searchable dropdown) |
| **Device**             | Desktop or Mobile                                       |

Once saved, Threadlytics checks the post's ranking on a scheduled basis (every 7 days) and logs each result.

## Ranking History

Click the history icon on any tracked post to open a detailed timeline of that post's Google rankings.

### History Table Columns

| Column       | Description                                       |
| ------------ | ------------------------------------------------- |
| **Date**     | When the ranking snapshot was taken               |
| **Position** | Rank at that point in time                        |
| **Page**     | Which page of Google results the post appeared on |
| **Change**   | Movement compared to the previous snapshot        |

Use this view to spot trends. For example, a Reddit thread that was ranking #5 last month and is now at #2 represents growing organic visibility.

## Bulk Actions

Select multiple tracked posts using the checkboxes and use the **Bulk Delete** option to remove several entries at once.

## How It Works

1. You submit a Reddit URL and a search keyword
2. Threadlytics searches Google for that keyword
3. The response is scanned for the Reddit URL in the results
4. The position is recorded as a snapshot with a timestamp
5. This process repeats every 7 days, building a historical record
6. The Change indicator on the main table reflects movement since the most recent snapshot


# Settings
Source: https://docs.threadlytics.io/pages/settings



## Overview

The Settings page is where you configure how Threadlytics behaves for your organization. This includes filtering, alerts, team management, data export, API access, and billing. Most settings are organization-wide and apply to all members.

> **Note:** Members with the Client Member role see a simplified profile-only view. Full settings are available to Admins and standard Members.

## Excluded Subreddits

Manage a blacklist of subreddits whose posts should be ignored across all keyword monitoring.

* **Add Subreddit** – type a subreddit name to add it to the exclusion list
* **Export CSV** – download your current exclusion list as a spreadsheet
* **Import CSV** – bulk-upload a list of subreddits to exclude
* **Cleanup Mentions** – removes any existing mentions that came from subreddits now on the exclusion list, retroactively cleaning your data

## Language & Content Filter Preferences

Fine-tune how Threadlytics processes and filters incoming Reddit content:

* **Language Preferences** – set which languages to include or prioritize
* **Content Filter Preferences** – adjust rules for minimum content length, URL-only post exclusion, and date range filtering

## Email Alerts

Configure real-time email notifications when new mentions are found.

| Setting                       | Description                                                                   |
| ----------------------------- | ----------------------------------------------------------------------------- |
| **Enable Alerts**             | Toggle to turn email alerts on or off                                         |
| **Alert Email Address**       | The address that receives alert emails                                        |
| **Frequency**                 | How often alerts are sent: every 15 minutes, 1 hour, or 24 hours              |
| **Minimum Opportunity Level** | Only send alerts for mentions at or above this score threshold                |
| **Keyword Type Filters**      | Choose which keyword types trigger alerts: Brand, Competitor, and/or Industry |

## Weekly Email Reports

A Monday morning summary email covering the previous week's activity.

| Setting            | Description                                             |
| ------------------ | ------------------------------------------------------- |
| **Enable Reports** | Toggle weekly reports on or off                         |
| **Recipients**     | Add or remove email addresses that receive the report   |
| **Send Now**       | Trigger a test report immediately to preview the format |

## Export Data

Download your data for external analysis or reporting.

| Option         | Description                                                                  |
| -------------- | ---------------------------------------------------------------------------- |
| **Data Type**  | Choose from Mentions, Sentiment Analysis, Opportunities, or Account Tracking |
| **Format**     | Export as CSV or JSON                                                        |
| **Date Range** | Pick a preset (7 days, 30 days, 6 months, All Time) or set a custom range    |

All exports enforce client-level access controls. You can only export data for clients you have permission to access.

## Team Members *(Admin only)*

Manage who has access to your Threadlytics organization.

### Invite Members

Send an invitation by entering an email address and selecting a role:

| Role              | Access Level                                                      |
| ----------------- | ----------------------------------------------------------------- |
| **Admin**         | Full access, including settings, billing, and team management     |
| **Member**        | Full access to monitoring features; cannot manage team or billing |
| **Client Member** | Read-only access to specific client data; restricted navigation   |

## Billing *(Admin only)*

View your current subscription and manage billing.

| Element                  | Description                                                                                        |
| :----------------------- | :------------------------------------------------------------------------------------------------- |
| **Current Plan**         | Displays your active plan (Standard, Pro, or Premium)                                              |
| **Status Badge**         | Shows whether your subscription is active, trialing, or past due                                   |
| **Trial / Billing Date** | When your trial ends or your next invoice is due                                                   |
| **Manage Billing**       | Opens the Stripe Customer Portal to update payment methods, download invoices, or change your plan |

## API Access *(Premium + Admin only)*

Generate and manage API keys for programmatic access to your Threadlytics data.

| Feature              | Description                                                                            |
| -------------------- | -------------------------------------------------------------------------------------- |
| **Generate API Key** | Creates a new token for use with the REST API                                          |
| **Revoke Key**       | Permanently invalidates an existing key                                                |
| **API Usage**        | Monitor how many requests have been made against your rate limit (2,000 requests/hour) |

Available API endpoints include `/api/v1/mentions`, `/api/v1/keywords`, `/api/v1/analytics/sentiment`, `/api/v1/analytics/top-sources`, and `/api/v1/serp`. All endpoints support filtering, pagination, and CSV export.


# Top Sources
Source: https://docs.threadlytics.io/pages/top-sources



## Overview

The Top Sources page shows you where on Reddit your tracked keywords are being discussed most. It identifies the most active communities (subreddits) and the most active individual users, helping you understand who is talking about your brand and where those conversations are happening.

## Tabs

The page is split into two views:

### Subreddits

A ranked table of the Reddit communities generating the most mentions of your tracked keywords.

| Column            | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- |
| **Subreddit**     | The community name (e.g., r/technology) — links directly to the subreddit on Reddit |
| **Mentions**      | Total number of keyword mentions found in that community                            |
| **Last Activity** | When the most recent mention from this subreddit was found                          |

Each subreddit name is a clickable external link that opens the community in a new tab.

### Users

A ranked table of the Reddit accounts most frequently mentioning your tracked keywords.

| Column        | Description                                                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **User**      | Reddit username (e.g., u/username) — links to their Reddit profile                                                                                                 |
| **Mentions**  | Total number of mentions attributed to this user                                                                                                                   |
| **Sentiment** | Color-coded badge showing this user's average sentiment: **Positive** (green), **Neutral** (grey), or **Negative** (red)                                           |
| **Active In** | The top subreddits where this user mentions your keywords, shown as clickable tags. If active in more than 2 communities, the rest are indicated with a "+X" count |

## Use Cases

* **Community targeting** – Identify which subreddits are most engaged with your brand so you know where to focus community efforts
* **Influencer discovery** – Find the most active and vocal users to understand who is shaping the conversation
* **Competitor comparison** – Cross-reference top subreddits with your competitor keywords to spot communities where rivals are getting more traction
* **Sentiment by source** – Use the Users tab to identify whether your loudest advocates are positive or negative, and which communities they come from


# Roles & Permissions
Source: https://docs.threadlytics.io/team/roles



Threadlytics uses a two-layer permission model: an **organization account type** (Standard, Pro, Premium) that controls what features are available, and a **user role** (Admin, Member, Client Member) that controls what each person can do within those features.

## Role Overview

|                                  | Admin | Member | Client Member            |
| -------------------------------- | ----- | ------ | ------------------------ |
| View dashboard & mentions        | ✅     | ✅      | ✅ (assigned client only) |
| View keywords, sentiment, trends | ✅     | ✅      | ✅ (limited pages)        |
| Manage keywords                  | ✅     | ✅      | ❌                        |
| Change org-wide settings         | ✅     | ❌      | ❌                        |
| Manage email alerts              | ✅     | ❌      | ❌                        |
| Invite & manage team members     | ✅     | ❌      | ❌                        |
| Change member roles              | ✅     | ❌      | ❌                        |
| Export data                      | ✅     | ❌      | ❌                        |
| Manage billing                   | ✅     | ❌      | ❌                        |
| Access API keys (Premium)        | ✅     | ❌      | ❌                        |
| Access multiple clients          | ✅     | ✅      | ❌ (single client only)   |

## Admin

Admins have full control over the organization. There is always at least one Admin (the person who created the account).

**What Admins can do:**

* Everything a Member can do
* **Settings** — change filtering, excluded subreddits, language preferences, and content filters for the whole org
* **Email alerts** — configure keyword alert emails, weekly report recipients, and alert frequency
* **Team management** — invite users, change roles, and remove members; enforces plan-based seat limits
* **Billing** — open the Stripe Customer Portal to manage the subscription, payment method, and plan
* **Data export** — export mentions, sentiment analysis, opportunities, and account tracking data
* **API access** (Premium plan only) — generate, view, and revoke API keys

**How to assign:** A new user can be made Admin from the Team Members card in Settings, or from the Users tab in the admin dashboard.

## Member

Members are standard users who can use the full monitoring and analytics features of the platform but cannot change organization-wide settings.

**What Members can do:**

* View and search all mentions
* View the dashboard, sentiment analysis, market analysis, top sources, trends, SERP tracking, and opportunities
* View keywords
* Manage Reddit accounts linked to the org
* View the Settings page (read-only for most options; can edit their own profile)

**What Members cannot do:**

* Change org-wide filtering or alert settings
* Invite or remove team members
* Access billing or export data
* Generate API keys

## Client Member

Client Members are a special role designed for agency use (Pro/Premium plans with Agency Mode enabled). They are external stakeholders (typically a client of your agency) who are given read-only access to reporting for a single specific client account.

**What Client Members can do:**

* View the **Dashboard**, **Market Analysis**, **Top Sources**, and **Sentiment** pages (scoped to their assigned client only)
* Access a limited **Settings** page (profile information only)

**What Client Members cannot do:**

* View any other client's data
* Access keywords, mentions list, trends, SERP, or opportunities pages
* Change any settings
* Access billing, exports, or API keys
* Switch between clients (they are locked to the one they were assigned)

## Inviting New Users

Admins can invite users directly from **Settings → Team Members**:

1. Enter the user's email address
2. Select a role: **Admin**, **Member**, or **Client Member**
3. For Client Member, also select which client they should access
4. Click **Add Member**

If the user already has a Threadlytics account, they are added immediately. If not, they receive an invitation email and are added to the org when they sign up.

## Changing A User's Role

**Within your organization (Settings page):**

1. Go to **Settings → Team Members**
2. Find the user in the member list
3. Use the role dropdown next to their name to switch between Admin and Member
4. To remove a user, click the remove button