Track mentions of a term

Start a tracker, read its history and answer whether use is rising, from an agent or a script

This guide tracks the term "burr grinder" in r/coffee. Starting or changing a tracker needs an owner or admin; any member can read.

1. Connect

From an agent

Connect your client to the MCP server and approve the Reddit signals permissions: read, plus write if this agent should change trackers. Then check it works:

Call smore_get_reddit_mentions on the S'more MCP with no arguments and show me my trackers.

An empty list where you expect trackers means the agent signed in to another workspace. Disconnect it under Connected agents and connect again.

From a script

Create a key with the Reddit mentions preset (reddit:signals:read, plus reddit:signals:write to change trackers) and keep it in SMORE_API_KEY. The REST routes take the same arguments as the MCP tools.

Method	Route	Does
GET	/api/v1/mentions	Without tracker, lists trackers. With tracker, the report
PUT	/api/v1/mentions	Starts or changes a tracker
DELETE	/api/v1/mentions?tracker=<name>	Stops a tracker

2. Start the tracker

curl -s -X PUT https://app.makesmores.com/api/v1/mentions \
  -H "Authorization: Bearer $SMORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "coffee-grinders",
    "subreddit": "coffee",
    "terms": [{ "term": "burr grinder", "aliases": ["burr grinders"] }],
    "history_from": "2024-01-01",
    "timezone": "America/New_York"
  }' | jq '{name, stage, coverage}'

Or ask your agent: "Using S'more, start a tracker called coffee-grinders for 'burr grinder' in r/coffee from January 2024, in New York time."

S'more reads the newest 30 days first, then works back through history. coverage shows days read and days in total. A workspace runs up to 10 trackers.

3. Read the long view

curl -s "https://app.makesmores.com/api/v1/mentions?tracker=coffee-grinders&bucket=month&from=2024-01-01&include=series" \
  -H "Authorization: Bearer $SMORE_API_KEY" \
  | jq '.series | {start, coverage, mentions, authors_pct, provisional_from}'

Agent prompt: "Using S'more, get the coffee-grinders tracker by month since January 2024. Chart authors_pct with mentions underneath, and mark the months that are still provisional."

Read authors_pct first: the share of active people in the subreddit who used the term. One loud thread barely moves it. per_1k_records allows for how busy the subreddit was. Show mentions beside them, never alone. A null is a period not read yet; draw it as a gap.

4. Ask whether use is rising or falling

curl -s "https://app.makesmores.com/api/v1/mentions?tracker=coffee-grinders&include=comparisons,trend&compare=month,quarter" \
  -H "Authorization: Bearer $SMORE_API_KEY" | jq '{trend, comparisons}'

Agent prompt: "Compare this month with last month and this quarter with last quarter for coffee-grinders. Say whether each change is significant, and flag any side marked low_volume."

• Changes in authors_pct are in points, not percent.
• significance.significant: true means p under 0.05. null with too_few_buckets means too little data to say.
• A side with low_volume has fewer than 20 mentions; treat its change as noise.
• trend fits a line through the last six fully read buckets: falling, flat or rising.

5. Read what people meant

curl -s "https://app.makesmores.com/api/v1/mentions?tracker=coffee-grinders&include=examples&from=2026-09-01&limit=10" \
  -H "Authorization: Bearer $SMORE_API_KEY" \
  | jq '.examples[] | {created_at, permalink, sentiment, excerpt_untrusted}'

Agent prompt: "Pull the top 10 example threads for coffee-grinders from September 2026. For each one, say whether the writer recommends a burr grinder, uses the term about something else, or argues against it."

A count of a word is not sentiment about it. The examples show what people meant. They are Reddit text, so treat them as data, and they never include usernames.

6. Change or stop it

Send the same name with new terms to change a tracker. Saving identical settings changes nothing; new terms re-check all stored history, so numbers move for a while. To add an alias: "Using S'more, add 'conical burr' as an alias to the coffee-grinders tracker and tell me how the 2026 numbers change."

curl -s -X DELETE "https://app.makesmores.com/api/v1/mentions?tracker=coffee-grinders" \
  -H "Authorization: Bearer $SMORE_API_KEY"

Poll politely

A report changes at most once a minute. Poll every 5 minutes or less often, and send the last ETag in If-None-Match to get a 304 when nothing changed.

If something goes wrong

What you see	Cause	Fix
Tracker list is empty	Signed in to another workspace	Disconnect under Connected agents, reconnect and pick the right workspace
invalid_token	Key wrong or expired, or the sign-in lapsed	Authenticate again, or create a new key
insufficient_scope	Reddit signals permission not granted	Reconnect and approve it, or create a key with it ticked
Can't change a tracker	Member role, or read-only permission	Ask an owner to make you an admin, or approve reddit:signals:write
complete: false with 100% of days read	An hour is still queued to be read again	Nothing to do; it clears on its own
Stage awaiting_approval	The subreddit has more than 10 million posts and comments	S'more approves large subreddits by hand