# Brand Mentions Monitor – Hacker News, Bluesky, News & GitHub (`kirozhang/brand-mentions-monitor`) Actor

Monitor mentions of your brand, product or competitors across Hacker News, Bluesky, Google News, Mastodon, Stack Overflow, GitHub and DEV. Only new mentions, sentiment, share of voice, keyword and viral-post alerts to Slack or a webhook.

- **URL**: https://apify.com/kirozhang/brand-mentions-monitor.md
- **Developed by:** [Kiro Zhang](https://apify.com/kirozhang) (community)
- **Categories:** Social media, News, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 mentions

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Brand Mentions Monitor – Hacker News, Bluesky, News & GitHub

Find out **who is talking about your brand, product or competitors** – across **Hacker News, Bluesky, Google News, Mastodon, Stack Overflow, GitHub and DEV Community** – in one run. Schedule it and get **only new mentions**, with **sentiment**, **share of voice**, **keyword alerts** and **viral-post alerts** in Slack or any webhook, plus a shareable report.

- ✅ **7 public sources, one format**: stories, comments, posts, articles, questions, issues and pull requests.
- ✅ **Exact-phrase matching** and exclude words to keep the noise out.
- ✅ **Only new mentions** mode for hourly or daily monitoring.
- ✅ **Share of voice**: add your competitors and see who gets talked about most.
- ✅ **Sentiment** on every mention, plus **alerts** for negative mentions, your keywords (`outage`, `pricing`, `alternative`…) and **high-engagement** posts.
- ✅ Real publisher URLs for news, engagement numbers (points, likes, reposts, comments) for social posts.
- ✅ Privacy-friendly: author handles are off by default.

### Who uses it

| You are | You get |
|---|---|
| **Founders & DevRel** | Every HN thread, Bluesky post, GitHub issue and Stack Overflow question about your product – in Slack. |
| **Marketing & PR** | News coverage and social buzz for your brand vs competitors, with share of voice. |
| **Customer success & support** | Complaints and "alternative to…" posts before they spread. |
| **Investors & analysts** | Momentum of a start-up or open-source project across communities. |

### How to use it

1. Add the **names to monitor** – your brand, product names, competitors, a campaign hashtag.
2. Pick the **sources** (default: all except GitHub, which is opt-in because developer tools get hundreds of pull-request mentions a day) and the **look-back window**.
3. For monitoring, turn on **Only new mentions**, set a **Tracking name**, add alert keywords and a Slack webhook, and schedule the run hourly or daily.

```json
{
    "queries": ["Supabase", "Firebase", "Appwrite"],
    "lookbackDays": 7,
    "onlyNew": true,
    "trackingId": "baas-share-of-voice",
    "alertKeywords": ["outage", "pricing", "alternative", "switched to"],
    "engagementAlert": 50,
    "slackWebhookUrl": "https://hooks.slack.com/services/…"
}
```

### Output

One row per mention:

```json
{
    "query": "Supabase",
    "source": "hackernews",
    "sourceName": "Hacker News",
    "type": "comment",
    "title": "Re: Show HN: Open-source Firebase alternative",
    "text": "We moved from Firebase to Supabase last year and…",
    "url": "https://news.ycombinator.com/item?id=50192022",
    "publishedAt": "2026-10-22T06:45:21Z",
    "engagement": { "points": null, "comments": null },
    "engagementScore": 0,
    "sentiment": "positive",
    "sentimentScore": 2,
    "matchedKeywords": [],
    "customTopics": [],
    "isAlert": false,
    "alertReasons": [],
    "isNew": true
}
```

Other fields by source: `newsSource` and `googleNewsUrl` (news), `repository` (GitHub), `tags` (Stack Overflow, DEV), `answered` (Stack Overflow questions), `language` (Bluesky, Mastodon), `linkUrl` (HN stories), optional `author`. `OUTPUT` holds mentions per name and source, share of voice, sentiment split, alerts and the top mentions by engagement.

### Pricing

| Event | Price |
|---|---|
| Mention saved | **$1.50 per 1,000 mentions** ($1.20 on Gold and higher Apify plans) |
| Name checked (all sources) | $0.003 per name per run |

Examples: 3 names, daily, ~40 new mentions a day in "only new mentions" mode ≈ **$2.10 / month**. Hourly monitoring of 1 name ≈ $2.20 / month plus mentions. The Apify free plan monitors up to 3 names per run.

### FAQ

**Why not X (Twitter), Reddit, Facebook or LinkedIn?** They require a login or a paid API for search. This Actor only uses sources that are public without logging in.

**How does Mastodon / DEV search work?** Both are searched by tag – the name without spaces (e.g. `#supabase`). Add more hashtags or Mastodon servers in the source settings.

**Is sentiment accurate?** It is a fast, rule-based English word list – good for sorting and alerts. Export the mentions to your AI tool for deeper analysis.

**Is it legal?** The Actor reads public posts and articles through public endpoints, does not log in, and leaves author names out unless you turn them on.

# Actor input Schema

## `queries` (type: `array`):

One name or phrase per line – your brand, product, competitors, a founder's name or a campaign hashtag, e.g. <code>Supabase</code>, <code>Firebase</code>. Each line is searched as an exact phrase. With several names you also get share of voice.

## `sources` (type: `array`):

Leave empty to search every source except GitHub. GitHub (issues & pull requests) is opt-in because it returns a very high volume for developer tools.

## `lookbackDays` (type: `integer`):

Time window searched on each run (and for the baseline in monitoring mode).

## `maxMentionsPerSource` (type: `integer`):

Upper limit per name and source in one run.

## `exactMatch` (type: `boolean`):

Keep only mentions whose text contains the phrase as whole words (removes noise such as partial matches). Google News and hashtag/tag results are kept as returned.

## `excludeKeywords` (type: `array`):

Optional. Drop mentions that contain any of these words, e.g. a homonym (<code>python snake</code>) or your own team's handles.

## `onlyNew` (type: `boolean`):

Off by default (every mention in the look-back window is returned, each with <code>isNew</code>). When on, the first run with a Tracking name returns the window as the baseline and later runs return – and charge – only mentions not returned before.

## `trackingId` (type: `string`):

Optional. A stable name for this set of names and sources (e.g. <code>acme-brand</code>). Runs with the same name share history. Default: derived from the input.

## `alertOnNegative` (type: `boolean`):

Mentions with negative sentiment (basic English word list) are flagged with <code>isAlert</code>. Every row has <code>sentiment</code> and <code>sentimentScore</code>.

## `engagementAlert` (type: `integer`):

Points + likes + comments + 2× reposts. A mention at or above this is flagged as "high engagement" (0 = off).

## `includeAuthors` (type: `boolean`):

Off by default (privacy-friendly). When on, rows include the public handle of the author.

## `alertKeywords` (type: `array`):

Optional. A mention that also contains any of these words is flagged as an alert, e.g. <code>outage</code>, <code>pricing</code>, <code>alternative</code>, <code>switched to</code>. Case- and accent-insensitive.

## `customTopics` (type: `array`):

Optional. One topic per line: <code>Topic name: word, phrase, word</code>, e.g. <code>Pricing: price, pricing, expensive, plan</code>. Matching mentions get the topic in <code>customTopics</code>.

## `slackWebhookUrl` (type: `string`):

Optional. A Slack <a href="https://api.slack.com/messaging/webhooks" target="_blank">Incoming Webhook</a> URL (https://hooks.slack.com/services/…). After a run you get one summary message in that channel. Stored encrypted.

## `webhookUrl` (type: `string`):

Optional. Any https endpoint (Make, Zapier, n8n, a Microsoft Teams workflow or your own server). Receives one JSON POST per run with counts, items and the report link. Stored encrypted.

## `notifyOn` (type: `string`):

When the Slack / webhook message is sent.

## `publicReport` (type: `boolean`):

Off by default. When on, the HTML report (share of voice, alerts, top mentions, 7- and 30-day trends) is kept at one fixed link per Tracking name (OUTPUT.reportUrl). Anyone with the link can open it; author names are never included.

## `newsEdition` (type: `string`):

Country and language of Google News results.

## `mastodonInstances` (type: `array`):

Optional. Default <code>mastodon.social</code>. Add others such as <code>fosstodon.org</code> or <code>hachyderm.io</code>.

## `mastodonHashtags` (type: `array`):

Optional. Mastodon is searched by hashtag (the name without spaces, e.g. #supabase). Add more hashtags here.

## `proxyConfiguration` (type: `object`):

Apify Proxy (datacenter) is used by default.

## Actor input object example

```json
{
  "queries": [
    "Supabase",
    "Firebase"
  ],
  "lookbackDays": 3,
  "maxMentionsPerSource": 30,
  "exactMatch": true,
  "onlyNew": false,
  "alertOnNegative": true,
  "engagementAlert": 50,
  "includeAuthors": false,
  "notifyOn": "alerts",
  "publicReport": false,
  "newsEdition": "US:en",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `mentions` (type: `string`):

No description

## `report` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        "Supabase",
        "Firebase"
    ],
    "lookbackDays": 3,
    "maxMentionsPerSource": 30
};

// Run the Actor and wait for it to finish
const run = await client.actor("kirozhang/brand-mentions-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "queries": [
        "Supabase",
        "Firebase",
    ],
    "lookbackDays": 3,
    "maxMentionsPerSource": 30,
}

# Run the Actor and wait for it to finish
run = client.actor("kirozhang/brand-mentions-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    "Supabase",
    "Firebase"
  ],
  "lookbackDays": 3,
  "maxMentionsPerSource": 30
}' |
apify call kirozhang/brand-mentions-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kirozhang/brand-mentions-monitor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/VO9ce7XvnImoXHMbG/builds/y2dznhprotQuw3bJK/openapi.json