General

Build a social listening dashboard

Collect public brand mentions, remove duplicates, and build a dashboard from real search responses. Includes storage, scheduling and spike checks.

Social FetchUpdated

Build a dashboard that answers two questions: which public posts matched your brand searches, and which IDs appeared since your previous checks? This guide collects TikTok, X, YouTube and Reddit results, then stores them in Postgres.

You need a Social Fetch API key, Node.js for the TypeScript SDK, a database and a scheduled worker. Start with the brand monitoring recipe to try the searches before writing storage code.

Search results are a sample of what your queries found. First-seen posts are not everything published about a brand. Treat the first successful poll as a baseline rather than sending spike alerts for all its results.

For scheduled alerts without a database, use Monitors. Search monitors record a baseline on the first successful check and send new matching posts on later checks. Creating one requires a workspace with a previous payment. Each successful check, including the baseline, costs the source's normal API price. Monitors do not calculate the custom dashboard metrics below.

  1. Open the Playground and choose Search Reddit posts.
  2. Set query to "Liquid Death", sortBy to new, and timeframe to week. Liquid Death is the public brand used in the saved examples.
  3. Click Send. Check the returned posts and credit charge before scheduling more calls.
Reddit search in the dark Playground, with the quoted brand query and newest-first weekly filters annotated; ordinary usernames in the response are blurred.
Test one query before putting it on a schedule. This completed search costs 1 credit.

Keep a watch list with a separate entry for each platform and query. Store its exact filters and schedule so you can explain later changes in results. Start with one brand term, then test misspellings and competitor terms before adding them.

For X, put operators inside query. For example, "Liquid Death" lang:en min_faves:5 asks for English posts with at least five likes. since:YYYY-MM-DD and until:YYYY-MM-DD can bound an incident window. The advanced search builder compiles these filters for you. The SDK accepts query, section, limit and cursor; do not pass language or minLikes as separate options. Avoid engagement thresholds when you want to find complaints before they attract likes.

Collect a poll with the SDK

Install the SDK in your worker project:

Request
bash

Set SOCIALFETCH_API_KEY in your worker's environment. Keep it on the server, outside browser code and source control.

This example fetches one page per platform and maps the different result fields to a small common row. YouTube's upload filter is this_week; TikTok's date filter is this-week.

Request
typescript

Call poll for each due watch term. Save each successful poll before moving to the next platform, and record failures separately. A failed Reddit request should not discard successful X results.

To collect more pages, pass that platform's data.page.nextCursor back as cursor with the same query and filters. Stop when hasMore is false, the cursor is missing, or you reach your page budget. Each completed page is another billed request. A later scheduled poll starts a fresh search; an old cursor is not a freshness checkpoint.

References: TikTok search, X search, YouTube search, Reddit search.

Store posts and query matches

Keep one post row per (platform, post_id), plus one match row per watch term and post. A post matching both a brand term and a campaign term belongs to both watch lists. Putting only one watch_term_id on the post would lose that relationship.

This schema is a starting point for your own database:

Request
sql

For each successful poll, use one database transaction:

  1. Lock its watch_terms row so overlapping runs cannot both establish the baseline.
  2. Insert poll_runs using meta.requestId. If that request is already stored, stop this ingestion attempt.
  3. Upsert mentions on (platform, post_id). Update text and last_seen_at, preserving first_seen_at.
  4. Upsert term_matches on (watch_term_id, platform, post_id). For an existing match, update only last_seen_at. New matches use the poll's capture time; set is_baseline to true if this watch term has no completed baseline.
  5. Mark baseline_completed_at after the first successful poll, even if it returned no posts. Commit before sending alerts.

Retrying ingestion of a saved response is different from making a new API request: the new request can cost credits even when it returns IDs you already stored. If the initial baseline includes several pages, finish that collection before marking the baseline complete. Store query options alongside the watch term and treat a changed query as a new watch term with its own baseline.

Store publication time separately from first-seen time. Search can surface an older post for the first time today. YouTube search dates can be approximate; do not make claims about exact publication minutes from them. A post disappearing from search does not prove it was deleted.

Read the dashboard

This custom dashboard visual uses the brand monitoring recipe's real saved responses. It is not a built-in Social Fetch dashboard. The second poll found 72 results; 12 platform/post-ID pairs had not been seen in the earlier poll. It collected only the first page of each search.

Custom dashboard from saved Liquid Death search responses, comparing returned results with first-seen IDs by platform; annotations identify new IDs and first-page coverage.
Returned results and new IDs answer different questions. Every search still had another page available.

Count unique platform/post-ID pairs across a group of terms. Do not add per-term counts together: the same post can match several queries. For a per-term chart, use term_matches.first_seen_at; for a global chart, use mentions.first_seen_at. Exclude baseline rows from alerts and mark the initial collection on your chart.

Real saved search rows showing platform, post ID, publication date and New or Seen status; authors and profile links are omitted.
New means first discovered by this collector. An older publication date can still appear beside a New badge.

Keep the request log, credits and pagination coverage beside your chart. A successful empty search is a measured zero; a failed or skipped search is missing data. Show that gap rather than drawing a zero.

Check for spikes

Compare like with like. This SQL counts the most recent completed UTC hour and compares it with the preceding seven days of completed hours for watch term 1. It includes quiet hours as zero and excludes baseline posts.

Only run it after a full baseline period with successful collection in every hour being compared. Check poll_runs for coverage first. If an hour lacks a successful poll, defer the alert or explicitly model missing coverage. Filling a failed hour with zero would make the baseline misleading.

Request
sql

The multiplier and minimum of ten are example thresholds, not measured properties of the brand. Tune them after reviewing your results. Keep an alert record keyed by watch term and hour so repeated runs do not send the same alert twice.

Send a short alert with the watch term, measured window, count, baseline and links to the posts behind it. Keep post URLs when extending the ingestion mapping if you need clickable alert citations. To chart the hourly counts against the baseline, point a BI tool such as Metabase or Looker Studio at term_matches.

Schedule and budget

Run the worker on a schedule you control. Avoid overlapping jobs for the same watch term. Record successes and failures, retry transient errors with backoff, and honour Retry-After when present. Treat validation and authentication errors as configuration problems rather than retrying them repeatedly.

Each completed search used here costs 1 credit, including an empty result. Budget by requests, including extra pages and manual tests:

Example scheduleRequestsCredits
3 terms on the platforms in this guide, one page each, hourly288 per day288 per day
5 X terms, one page each, every 15 minutes480 per day480 per day
10 Reddit terms, two pages each, one collection2020

Use meta.creditsCharged for actual totals and the request log to inspect individual calls. Failed lookups are not charged. Paid API calls have no request quotas, but capacity errors can occur; start with a small batch. See Credits.

Troubleshooting

TypeScript rejects language, minLikes or uploadDate: "week"

Use X operators inside query, and uploadDate: "this_week" for YouTube. TikTok video search is client.tiktok.searchVideos, with sortBy: "date-posted" for date ordering. Copy parameters from each route's reference rather than sharing one parameter object across platforms.

The dashboard keeps counting the same posts

Count first-seen rows rather than results returned by each poll. Preserve first-seen timestamps on upsert, dedupe on platform and post ID, and keep each query match in its own join row.

A spike appears after adding a watch term

Treat that term's first successful poll as its baseline. Keep baseline rows out of spike counts. Check for query changes, failed collection windows and missing zero hours before changing the alert threshold.

Search is empty but a post is visible in a browser

Try a less restrictive query in the Playground. Search coverage and ranking can differ from a direct post lookup. Do not promise complete coverage from this collector.

lookup_failed or temporarily_unavailable

Record the error code and request ID. Retry transient failures with backoff and use Retry-After when supplied. Leave a collection gap visible if retries fail. Contact support with the request ID if it persists.

FAQ

Do I need to build a worker?

Use Monitors for scheduled search checks and signed webhook delivery. Build your own worker for custom storage, query groups or spike calculations.

Does new mean newly published?

No. A post can enter search results after publication. Count first-seen IDs separately from publication dates, and label each chart clearly.

Does an empty search cost credits?

A completed search costs its normal price even when it finds nothing. Failed lookups are not charged. Record meta.creditsCharged for each successful request.

Will this find every mention?

No. Search returns public results available for your query and filters. Rankings, coverage and your pagination budget affect what you collect.

Share this article