Social Listening API: Track Brand Mentions

A social listening tool watches social media for mentions of your brand, product or topic, and tells you about new ones. You can build a working one with a social listening API and about 60 lines of Python: search each platform on a schedule, keep the posts you haven't seen, and send them to Slack. This guide builds it for Reddit, Threads and YouTube, and tracks a TikTok hashtag's growth alongside.

What social listening needsCopy Anchor Link

• Search on each platform, sorted by newest where the platform allows it.
• A schedule, so new mentions arrive within the hour.
• Deduplication, so each mention is reported once.
• An alert: Slack, email, or a row in a database.

Listening suites bundle all that with dashboards at an enterprise price. If you want the raw mentions in your own tools, an API and a cron job do the job.

The endpointsCopy Anchor Link

Every one answers in the same envelope, so one function handles them all.

Set your key and base URL:

export API_KEY="your-api-key"
export API_URL="https://api.socialparse.dev"

The listening scriptCopy Anchor Link

import json
import os

import requests

API_URL = os.environ["API_URL"]
HEADERS = {"x-api-key": os.environ["API_KEY"]}
SLACK_WEBHOOK_URL = os.environ.get("SLACK_WEBHOOK_URL")  # optional
SEEN_FILE = "seen.json"
KEYWORDS = ["your brand", "yourbrand.com"]


def search(path, params):
    response = requests.get(f"{API_URL}{path}", params=params, headers=HEADERS, timeout=120)
    if not response.ok:
        error = response.json()["error"]
        print(f"skipped {path}: {error['code']}")
        return []
    return response.json()["data"]


def mentions(keyword):
    """New-ish mentions of a keyword on each platform, as (platform, url, text) rows."""
    rows = []
    for post in search("/v1/reddit/search", {"q": keyword, "sort": "new"}):
        rows.append(("reddit", post["url"], post["title"]))
    for post in search("/v1/threads/search", {"q": keyword}):
        rows.append(("threads", post["url"], post["text"]))
    for video in search("/v1/youtube/search", {"q": keyword, "time": "day"}):
        rows.append(("youtube", video["url"], video["title"]))
    return rows


def alert(platform, url, text):
    message = f"[{platform}] {(text or '')[:200]}\n{url}"
    print(message)
    if SLACK_WEBHOOK_URL:
        requests.post(SLACK_WEBHOOK_URL, json={"text": message}, timeout=30)


def main():
    try:
        with open(SEEN_FILE) as file:
            seen = set(json.load(file))
    except FileNotFoundError:
        seen = set()

    for keyword in KEYWORDS:
        for platform, url, text in mentions(keyword):
            if url in seen:
                continue
            seen.add(url)
            alert(platform, url, text)

    with open(SEEN_FILE, "w") as file:
        json.dump(sorted(seen), file)


if __name__ == "__main__":
    main()

The first run reports everything it finds and fills seen.json. After that, each run reports only new mentions.

Run it every hourCopy Anchor Link

With cron:

0 * * * * cd /path/to/listener && API_KEY=... API_URL=... /usr/bin/python3 listen.py >> listen.log 2>&1

A GitHub Actions schedule or any task runner works the same way; keep seen.json somewhere that persists between runs.

Track a TikTok hashtag's growthCopy Anchor Link

TikTok listening is often about a campaign hashtag. The hashtag endpoint answers its video_count and total views; save them daily and chart the growth:

import csv
import datetime

response = requests.get(
    f"{API_URL}/v1/tiktok/hashtags", params={"tag": "yourcampaign"}, headers=HEADERS, timeout=120
)
data = response.json()["data"]
with open("hashtag.csv", "a", newline="") as file:
    csv.writer(file).writerow([datetime.date.today().isoformat(), data["video_count"], data["views"]])

To read what people say under your own TikTok videos, add the video comments endpoint; the TikTok comments guide shows how.

What it costsCopy Anchor Link

One credit per successful search, errors free. Two keywords on three platforms, every hour, is 6 calls an hour: 144 credits a day. Hourly is plenty for most brands; every 15 minutes suits a launch day. New accounts get 100 free credits; see pricing and Credits for rate limits.

Going furtherCopy Anchor Link

• Sentiment. Score each mention with VADER, as in the Reddit sentiment analysis guide, and alert only on negative ones.
• Context. For a Reddit mention, fetch the thread with post comments.
• Competitors. Add their names to KEYWORDS and compare share of voice week by week.
• A database. Swap seen.json for a table once you want a dashboard.

Respect deletionsCopy Anchor Link

When someone deletes a post, it should leave your tool too. Social Parse never serves deleted content from its cache; if you store mentions, re-check old ones before showing or exporting them, and drop those that answer 404 NOT_FOUND.

FAQCopy Anchor Link

What is a social listening API?Copy Anchor Link

An API that searches social platforms for keywords and returns the matching posts as data, so you can build alerts, dashboards and reports in your own tools.

Can I monitor TikTok mentions by keyword?Copy Anchor Link

Social Parse doesn't offer TikTok keyword search. Track campaign hashtags with the hashtag endpoint and the comments on your own videos instead.

How fast are new mentions picked up?Copy Anchor Link

As fast as your schedule: an hourly job finds a mention within the hour of it appearing in the platform's search.

Is social listening allowed?Copy Anchor Link

Listening for brand and topic mentions in public posts is standard practice. Don't use it to track or profile individuals: Social Parse's terms rule that out.

How do I start?Copy Anchor Link

Create a key, follow the quickstart, then run the script above with your brand's name.