Social listening API for X, Reddit, TikTok, Instagram and the news
Track brand mentions and conversations on X, Reddit, TikTok, Instagram, YouTube, Threads, Telegram and Google News with one API key. Pay per post.
Collect what people say about your brand, your competitors or a topic across X, Reddit, TikTok, Instagram, YouTube, Threads, Telegram and Google News, as JSON you can store, chart or hand to a model. Together they work as a social listening API: each platform is a data tool with its own search filters and a price per post, comment or article. Run them on your own schedule from code, or let an AI agent run them over MCP.
Hand it to your AI agent
Copy this prompt into Claude Code, Cursor, Codex or any coding agent. It tells the agent where the docs are and how to use your API key.
Track mentions and conversations about a brand or topic on X, Reddit, TikTok, Instagram, YouTube, Threads, Telegram and Google News. Use the Lovely Router data tools: each returns JSON and is billed per result.
- Docs (read first): https://lovelyrouter.com/docs/tools/find.md and https://lovelyrouter.com/docs/tools/run.md
- Plan first: POST https://lovelyrouter.com/v1/tools/suggest with `{"task": "<my task in plain words>"}` (free). It returns the tools to run in order, each with an example `input`, the `input_required` fields, an estimated cost and a ready-made `run` request. Replace the example values with my task's; if a field is unclear, read the tool with GET https://lovelyrouter.com/v1/tools/<id>. To browse instead, POST https://lovelyrouter.com/v1/tools/discover searches the catalog.
- Show me the plan and its estimated cost (`total_est_cost_usd`) before running anything large.
- Run: POST https://lovelyrouter.com/v1/tools/<id>/run with `{"input": {...}, "max_results": N}`. A 200 has the finished run with `items`; a 202 means it is still running, so poll the `poll` path until `status` is `succeeded`, `failed`, `timed_out` or `stopped`.
- Only delivered results are billed. Keep max_results small on the first run, check the output, then scale up.
- If you support MCP, connect https://lovelyrouter.com/mcp instead (Streamable HTTP, same key; https://lovelyrouter.com/docs/tools/mcp.md) and use suggest_tools, get_tool and run_tool.
- Auth: read my API key from the LOVELY_API_KEY environment variable and send it as `Authorization: Bearer $LOVELY_API_KEY`. Never print or commit the key. If it is not set, ask me to create one at https://lovelyrouter.com/app/keys.
- Billing is prepaid: every call is charged to my balance, so test with a small request before running anything large.
- Every docs page is plain Markdown; the full index is https://lovelyrouter.com/llms.txt.
My task: <the brand or keywords, the platforms, the time window and how to summarize what you find>How it works
Find the mentions
Search tools return posts that match your keywords, hashtags or operators: X search, Reddit search, TikTok search, Instagram hashtags, Threads and Google News.
Pull the conversation
Send the posts that matter to the comment tools: X replies, Reddit comments, TikTok comments, Instagram comments and YouTube comments.
Read it with a model
Pass the text to a model on the same key, such as
claude-sonnet-5.5, to group it by topic and sentiment, or to pull out complaints and questions.
Monitor brand mentions on X
This run collects the week's English posts that mention a brand, leaving out the brand's own account:
curl https://lovelyrouter.com/v1/tools/x-search/run \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{
"input": {
"searchTerms": ["\"brewbox\" OR @brewbox -from:brewbox lang:en since:2026-10-13"],
"queryType": "Latest",
"maxItems": 200
},
"max_results": 200
}'Each item in items is one post with its text, author, engagement and date. Every entry in searchTerms is written like X's search box, so the operators work: "exact phrase", OR, -word, from:, to:, since: and until:, min_faves:, filter: and lang:. queryType returns Latest, Top or Latest + Top. A run that takes longer than 60 seconds answers 202; poll it as shown in Run a tool.
Turn mentions into a report
The same key calls the model. This script pulls a week of Reddit posts and asks Claude what people complain about:
import json
import os
import anthropic
import requests
KEY = os.environ["LOVELY_API_KEY"]
run = requests.post(
"https://lovelyrouter.com/v1/tools/reddit-search/run",
headers={"Authorization": f"Bearer {KEY}"},
json={"input": {"queries": ["brewbox"], "sort": "new", "timeframe": "week"}, "max_results": 50, "wait": 120},
timeout=150,
).json() # a run still going after `wait` comes back as 202: poll it
client = anthropic.Anthropic(base_url="https://lovelyrouter.com", api_key=KEY)
msg = client.messages.create(
model="claude-sonnet-5.5",
max_tokens=1500,
messages=[{"role": "user", "content": "Group these Reddit posts about Brewbox by topic and sentiment, "
"and quote the three most common complaints:\n" + json.dumps(run["items"])}],
)
print(msg.content[0].text)Model tokens are billed per token at the model's price; see models.
The tools
Tweets matching search terms, hashtags or from given handles: text, author, engagement, date. Each search term takes X's advanced search operators (from:, since:, min_faves:, filter:, lang: …).
Replies to X/Twitter posts by URL: text, author, engagement, date.
Reddit posts for a query or subreddit: title, body, score, comments count, author, date.
A Reddit thread's post and comments by URL: text, score, author, date, reply depth.
TikTok videos for keywords or hashtags: caption, views, likes, shares, author, music.
Comments on a TikTok video by URL.
Posts or reels for Instagram hashtags or keywords: caption, likes, comments, author, media.
Comments on Instagram posts or reels by URL: text, likes, replies count, author, date.
Comments on YouTube videos or Shorts: text, likes, replies count, author, date. Sorted by top or latest.
Threads posts from users, a keyword search or a thread: text, likes, replies, reposts, views, media, date.
Messages from public Telegram channels posted on or after oldestMessageDate (YYYY-MM-DD).
News articles from Google News for a search (operators work: "exact phrase", OR, -word, site:, intitle:), optionally within a time window: title, source, date and the article's link on the publisher's site.
| Platform | Find posts | Get the conversation | Filters worth knowing |
|---|---|---|---|
| X | x-search: text, author, engagement, date | x-replies by postUrls | X operators, queryType, lang, twitterHandles |
reddit-search: title, body, score, comment count, author, date | reddit-comments by thread urls, with reply depth | subredditName, sort, timeframe | |
| TikTok | tiktok-search: caption, views, likes, shares, author, music | tiktok-comments by video URL | dateRange, sortType, location, includeReplies |
instagram-hashtag: caption, likes, comments, author, media | instagram-comments: text, likes, replies count | hashtag startUrls or keywords, sortOrder | |
| YouTube | find videos with YouTube search | youtube-comments: text, likes, replies count | sort: top or latest |
| Threads | threads-posts with mode search | threads-posts with mode thread | postedAfter, postedBefore |
| Telegram | telegram-channel: public channel messages | oldestMessageDate | |
| News | google-news: title, source, date, link | operators, openEndedDateRange, language |
Tip
Use each tool's date filter so a scheduled run doesn't pay for posts you already have: since: on X, timeframe on Reddit, openEndedDateRange on Google News, postedAfter on Threads and oldestMessageDate on Telegram.
Recipes
Every morning, run x-search with since: set to yesterday, reddit-search with "timeframe": "day", google-news with "openEndedDateRange": "1d" and threads-posts in search mode with postedAfter. Merge the results and ask a model for a one-page summary.
After you publish a launch video, run youtube-comments with "sort": "latest" on it and tiktok-comments with "includeReplies": true on your TikTok posts. Ask a model for the most common questions.
Run reddit-search for the competitor's name with "sort": "comments", then reddit-comments on the most discussed threads.
Run instagram-hashtag on https://www.instagram.com/explore/tags/yourcampaign/ and tiktok-search with the same hashtag in keywords and "sortType": "DATE_POSTED".
Add min_faves:100 to an X search term to catch posts about you that are gaining traction, and watch the public Telegram channels in your market with telegram-channel.
Run it from an agent
With the MCP server connected (claude mcp add --transport http lovely-tools https://lovelyrouter.com/mcp --header "Authorization: Bearer $LOVELY_API_KEY"), ask Claude Code or Cursor: "Find what people said about Brewbox this week on X, Reddit and TikTok, read the replies under the five most discussed posts, and summarize the praise and the complaints with links. Set max_results on every run."
What you pay
Social tools bill per result: per post, comment, video, message or article, and a few add a per-call fee. The cards above show today's prices. Starting a run holds its maximum cost, the per-call fee plus the per-result fee times max_results, and the run settles to what it returned. A failed run pays only for results it delivered, so one that returned nothing costs nothing. There is no subscription: you top up one prepaid balance shared with models and the browser agent. See pricing.
Frequently asked questions
Can I monitor brand mentions on several platforms with one API?+
Yes. Every platform is a tool behind the same endpoint, POST /v1/tools/{id}/run, with the same API key and prepaid balance. Inputs differ per tool, so read each tool's input schema with GET /v1/tools/{id} or on its tool page.
Does the API return sentiment scores?+
No. The tools return the posts and comments themselves. Send the text to a model on the same key, such as claude-sonnet-5.5, and ask for sentiment, topics or complaints in the format you need.
Can I use X advanced search operators?+
Yes. Each entry in the x-search searchTerms list is written like X's search box, with "exact phrase", OR, -word, from:, to:, since:, until:, min_faves:, filter: and lang:.
How do I avoid collecting the same posts twice?+
Run on a schedule and set each tool's date filter to the time since the last run: since: on X, timeframe on Reddit, openEndedDateRange on Google News, postedAfter on Threads and oldestMessageDate on Telegram.
Can an AI agent do the listening for me?+
Yes. Connect the MCP server to Claude Code, Cursor or another MCP client, and the agent finds the right tool with suggest_tools, reads its schema and runs it, billed from your balance. Give it a key with a spend limit.
For creators and their audiences, see influencer research; for star ratings, see review monitoring; for Xiaohongshu, Douyin and Weibo, see Chinese social media data.