Social Listening API: Real-Time Mentions, Comments, and Reviews (2026)

A social listening API collapses mentions, comments, DMs, and reviews from every connected account into one signed JSON payload delivered to one HTTPS endpoint. Register the endpoint once with POST /v1/webhooks, verify the X-SocialAPI-Signature header, deduplicate on the interaction id, and the read side of a listening product is done. The plumbing was never the hard part. The hard part is that the platforms disagree about what a mention is, and most of them will not sell you yesterday.

So design against the floor, not the ceiling: treat push delivery as forward-only from the moment you subscribe, and treat historical search as a per-platform privilege you probably do not have. X sells a Post archive back to March 2006 on its pay-per-use and Enterprise tiers (X, search introduction). Telegram throws away an unretrieved bot update after 24 hours (Telegram Bot API). Same category of product, four orders of magnitude apart.

What a social listening API does that a scraper cannot

Scrapers and listening APIs answer different questions. A scraper reads what is public. An authenticated API reads what an account owner granted you access to, which includes surfaces no scraper can reach and, more usefully, lets you write back into the same thread you just read. Monitoring without a reply path is a dashboard. Monitoring with one is a product.

The gap shows up four ways, and only the first one is obvious.

• Replying. A scrape hands you a string. POST /v1/inbox/comments/{id}/reply hands you a comment that exists on Instagram, posted by the account that authorized you, with a sapi_cmt_ id you can key an audit log on.
• Private surfaces. Direct messages are never on a public page. Instagram, Facebook, and Telegram DMs arrive through authorized connections or they do not arrive at all.
• Review platforms. Google Business Profile review replies go through the API and nowhere else. POST /v1/inbox/reviews/{id}/reply writes the response that customers see under the star rating.
• Stability. Markup changes on someone else's release schedule and takes your parser with it. A versioned API changes on a published deprecation calendar, which is a worse day at a better time.

Legal exposure is the fifth difference, and the one that ends procurement conversations. Scraping a logged-in surface breaches most platform terms of service outright, and the risk lands on whoever runs the scraper. An authorized integration moves the question to a consent screen the account owner clicked through POST /v1/accounts/connect. That is a defensible answer when a customer's security team asks how you came to hold their DMs.

There is a cost, and it is worth naming up front. Every platform gates authorized access behind its own OAuth flow, its own token lifetime, and usually its own review process: seven of the nine platforms we connect require an approval before your code touches a stranger's account. That arithmetic is the subject of social media API integration. A listening API is the thing you buy so you never learn it firsthand.

How mentions get resolved across platforms

Three mechanisms exist, and every platform picks exactly one. Some treat a mention as a first-class event and push it at you. Some expose no mention concept at all but let you run a keyword query against public posts, which is a search problem wearing a listening costume. Some give you nothing, and no abstraction layer can manufacture data a platform withholds.

Instagram and Facebook are the pull-friendly pair. GET /v1/mentions returns posts and stories where the connected account was tagged or @-mentioned, accepts a since timestamp in RFC 3339 and a cursor, and normalizes both platforms into the same interaction shape. Ask any other platform for mentions and you get a typed 501 rather than an empty array pretending to be an answer.

curl "https://api.social-api.ai/v1/mentions\
?account_id=acc_01HZ9X3Q4R5M6N7P8V2K0W1J&since=2026-08-01T00:00:00Z&limit=2" \
  -H "Authorization: Bearer $SOCAPI_KEY"

# {
#   "data": [
#     {
#       "id": "sapi_mnt_aW5zdGFncmFtOjE3ODk1Njk1",
#       "platform": "instagram",
#       "type": "mention",
#       "author": { "id": "17841405793187218", "name": "Sarah Dev" },
#       "content": { "text": "shipped this on @acme today" },
#       "created_at": "2026-08-02T09:14:00Z"
#     }
#   ],
#   "count": 1
# }

# Any platform without mention tracking:
# 501 { "error": { "code": "resource.not_supported" } }

Threads is the interesting exception, because it inverts the usual asymmetry. Meta gates Threads mention data behind Advanced Access and the threads_manage_mentions scope, delivers it by webhook, and publishes no endpoint that lists past mentions of your profile. You can receive every Threads mention from today forward and still have no way to ask what happened last Tuesday.

What Threads does offer instead is /keyword_search, which queries public posts with since and until down to Unix timestamp 1688540400, the day Threads launched in July 2023, at up to 2,200 queries per rolling 24 hours (Meta, Threads keyword search). Searching your own brand name is not the same as being told you were mentioned. It is the closest thing available.

Which events push, and which ones you can fetch back

That table is the inbox family only. Publishing lifecycle events (post.published, post.failed, and the rest of the posts category) are a separate set answering a different question, which is what happened to content you sent rather than what arrived from someone else. GET /v1/webhooks/events returns the authoritative catalog of both, and the feed-building side of the posts category is covered in the social media aggregator API guide.

Read the mention.received row twice, because it is the row that breaks product plans. Three platforms push mentions and two let you fetch them. If your onboarding flow promises a new customer "we'll pull your last 90 days of mentions," that promise is deliverable on Instagram and Facebook and false everywhere else. The entity model behind these ids, and why a mention stores differently from a comment, is covered in the social media mentions API guide.

TikTok and LinkedIn deserve a footnote each. TikTok's only documented comment-query surface is its Research API, capped at a 30-day range per query and explicitly closed to commercial users (TikTok, Research API). LinkedIn keeps mention data inside its Compliance API, which needs a private partner agreement. Neither gap is a bug in your integration.

Webhook delivery, retries, and why your consumer must deduplicate

Delivery is a contract with four terms: HTTPS only, an HMAC-SHA256 signature over the raw body, a 2xx inside 10 seconds, and retries on anything else. The signature is the part teams skip and regret, since a public URL that trusts its own request body is an open write endpoint for anyone who finds it. Constant-time compare, always. The full verification code for Node, Python, and Go is in webhook signature verification.

The retry schedule is where the deduplication requirement comes from. Five attempts, exponential backoff, fixed and documented: immediate, then roughly 30 seconds, 5 minutes, 30 minutes, and 3 hours. After the fifth attempt the delivery is marked failed and nothing else is tried automatically. Nothing retries forever. Nothing disappears quietly either.

Retries are the obvious duplicate source. They are not the biggest one. A reconciliation poll that deliberately overlaps the window push already covered will re-surface mentions you handled hours ago, which is the correct design and a permanent duplicate generator. Both problems have the same one-line fix: claim the interaction id before you do any work.

import crypto from "crypto";

app.post("/hooks/socapi", express.raw({ type: "application/json" }), async (req, res) => {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", process.env.SOCAPI_WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");

  const sig = req.headers["x-socialapi-signature"] ?? "";
  if (
    expected.length !== sig.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))
  ) {
    return res.status(401).send("bad signature");
  }

  res.sendStatus(200); // acknowledge inside 10s, then work

  const { event, data } = JSON.parse(req.body);

  // The id prefix encodes the type: no lookup, no switch on platform.
  // claim() is SETNX-shaped: false means a retry or an overlapping
  // reconciliation poll already delivered this exact interaction.
  if (!(await store.claim(data.id))) return;

  if (event === "mention.received") await queue.push("score-sentiment", data);
});

Two operational endpoints turn a silent pipeline into a debuggable one. GET /v1/webhooks/{id}/deliveries?status=failed lists every delivery that burned all five attempts, with the HTTP status and duration your endpoint returned each time. POST /v1/webhooks/{id}/deliveries/{did}/retry replays one after you ship the fix. Wire both into your ops dashboard on day one, not on the day of the incident. The full setup walkthrough lives in social listening webhooks.

Retry policies vary enough between platforms that you cannot assume yours. Meta retries a failed Graph API webhook "immediately, then a few more times with decreasing frequency over the next 36 hours," and drops unacknowledged updates after that (Meta, webhooks getting started). LinkedIn redelivers "once every 5 minutes for 8 hours" (LinkedIn, social action notifications). Ours stops at 5 attempts and roughly 3 hours, and keeps the payload replayable afterwards.

An idempotent consumer is not a nice-to-have. It is the price of every retry policy on the market, including the ones you did not read.

What social data APIs can and cannot retain

Sort the nine platforms into three groups and the whole retention question gets simple. Group one has a real archive you can query backwards. Group two has a short buffer that looks like an archive until you test it. Group three is forward-only from the moment you subscribe, full stop. Every claim below links to that platform's own documentation, checked on 3 August 2026.

• Real history: Google Business Profile returns every review a location has ever received through reviews.list, paginated at 50 per page (Google). X sells full-archive search back to March 2006 to pay-per-use and Enterprise customers (X); the free-standing recent endpoint covers only the last 7 days (X).
• Real history with a shape you did not expect: Facebook exposes /{page-id}/tagged, which Meta describes as "all public posts in which the page has been tagged" (Meta), while the Page /feed edge is capped at roughly 600 ranked posts per year and 100 per request (Meta). YouTube documents no time bound at all on commentThreads.list, but allThreadsRelatedToChannelId only covers your own channel (Google).
• Short buffers that fake it: LinkedIn keeps organization notifications "for 60 days" and calls webhooks the recommended path (LinkedIn). Telegram holds an unretrieved bot update for at most 24 hours (Telegram). Instagram's hashtag search returns "media objects published within 24 hours of query execution" and caps you at 30 unique hashtags per 7 days (Meta).
• Forward-only or nothing: Instagram @mentions have no documented endpoint that lists past mentions of your account, only an edge that resolves a media ID a webhook already gave you. Threads mentions push and never poll. TikTok has no commercial mention or comment query surface at all.

Our own storage stance follows from that split rather than fighting it. Mention content lives on a surface the account owner does not control and can be edited or deleted by its author at any time, so we proxy it in real time rather than keeping a durable mirror. Comments and reviews attach to something you own, so they behave like records. Delivery metadata is retained either way: that is what makes replay possible.

The practical consequence for anyone building on top: subscribe before you need the data, not when the incident starts. A brand monitor that goes live on Monday has no opinion about last week, and on six of nine platforms it never will. If the metrics side of the same problem is on your roadmap, the per-platform gaps in reach, impressions, and saves are laid out in the social media analytics API guide.

Questions developers ask about social listening APIs

What is a social listening API?

A social listening API is an authenticated interface that collects mentions, comments, direct messages, and reviews from connected social accounts and delivers them in one normalized shape, usually over webhooks. It differs from a social listening dashboard in that your own code acts on each event: route a negative mention to support, score sentiment, open a ticket, post a reply. SocialAPI.ai delivers the six inbox event types to one HTTPS endpoint, signs each payload with HMAC-SHA256, and gives every interaction a stable id you deduplicate on. Publishing lifecycle events live in a separate posts category, so subscribing to listening does not flood your endpoint with your own outbound activity.

What is the difference between a social data API and a social listening API?

Social data API is the broader term: any programmatic access to platform data, including profile metadata, post metrics, follower counts, and public search. Social listening API names the inbound slice of that, meaning the events that arrive because someone engaged with or referenced an account you control. In practice the same product usually covers both, but the engineering shape differs. Listening is push-oriented and latency-sensitive; the rest of a social data API is pull-oriented and quota-sensitive.

Which platforms allow historical mention search?

Very few, and the answer is per platform rather than per vendor. X offers full-archive search back to March 2006 on pay-per-use and Enterprise tiers, with a 7-day window on recent search. Facebook exposes historical tagged posts through the /{page-id}/tagged edge. Threads offers keyword search over public posts back to July 2023 but no list of past mentions of your own profile. Google Business Profile returns a location's complete review history. Instagram @mentions, TikTok, and Telegram are forward-only or unavailable, so a listening pipeline on those platforms only knows what happened after you subscribed.

Can you get social media data without scraping?

Yes, and for anything involving a reply you have to. Authorized APIs reach surfaces scraping cannot see, including direct messages and Google Business Profile review replies, and they let you write back into the same thread with an audit trail. The trade-off is that every platform gates that access behind OAuth, token refresh, and usually an app review. A unified API removes those gates by operating the platform apps for you; it does not remove the platform limits underneath.

How fast do mentions arrive over a webhook?

Seconds, versus a 1 to 15 minute floor for polling that is set by your interval rather than by the platform. The latency you control is your own: a handler that acknowledges with a 2xx inside 10 seconds and queues the real work behind it stays fast under load, while one that scores sentiment inline before responding will hit the timeout and trigger a retry storm of its own making. Push also costs nothing when nothing happens, which matters because most accounts are quiet most of the time.

What happens if my listening endpoint is down when a mention fires?

SocialAPI.ai retries the delivery 5 times with exponential backoff: immediate, then roughly 30 seconds, 5 minutes, 30 minutes, and 3 hours. After the fifth failure the delivery is marked failed rather than dropped, and you can list it with GET /v1/webhooks/{id}/deliveries?status=failed and replay it with POST /v1/webhooks/{id}/deliveries/{did}/retry once the endpoint is healthy. Because the same interaction id arrives on every attempt, your handler must be idempotent or a two-hour outage will fan out into duplicate alerts.

Is there a free social data API for agencies to test with?

SocialAPI.ai's free tier covers 2 brands, 10 posts a month, and 50 interactions a month with no credit card, and it exercises the same endpoints and webhook events as the paid tiers, so a proof of concept is not a different code path. Agencies running many client accounts are the case the per-brand pricing is built for: $29/mo for 10 brands, $109/mo for 50, $349/mo for 200, with unlimited posts and interactions above the free tier. Every brand is isolated, so one client's rate limits and tokens never touch another's.

To wire real-time listening across nine platforms without nine webhook integrations, read the webhooks guide, check the interaction id reference, or start on the free tier and register an endpoint in about five minutes.

Primary platform documentation cited above, all accessed 3 August 2026: X: search introduction (full archive to March 2006, tier availability) · X: recent search (7-day window) · Meta: Graph API webhooks getting started (36-hour retry ceiling) · Meta: Page /tagged edge (public posts tagging a Page) · Meta: Page /feed edge (~600 ranked posts per year, 100 per request) · Meta: Instagram hashtag recent media (24-hour window, 30 hashtags / 7 days) · Meta: Threads keyword search (since/until floor, 2,200 queries / 24h) · Meta: Threads webhooks (mentions field) · LinkedIn: organization social action notifications (60-day retention, 8-hour redelivery) · Google: Business Profile reviews.list (full review history, pageSize 50) · Google: YouTube Data API commentThreads.list · TikTok: Research API query specs (30-day range, eligibility) · Telegram: Bot API getUpdates (24-hour update retention) · SocialAPI.ai: webhooks guide (event types, signature scheme, retry schedule)