What is a social media mentions API?

A social media mentions API reads the places your brand is named or tagged across the platforms you have connected and returns each one in a single normalized interaction object. A mention is a reference to you on a surface you do not own, which makes it a discovery stream rather than an inbox you control. The same handler can process a mention from any platform because the shape and the stable id are identical regardless of where the mention originated.

Is a brand monitoring API the same thing as a mentions API?

They describe the same mechanism from two angles. Mentions API names the data: every reference to your brand, normalized. Brand monitoring API names the job that data serves: tracking and responding to what is said about you. In practice you use one API to read mentions and then build the monitor (dedupe, sentiment, alerting, storage) on top of it. The API is the read layer; the monitor is what you do with it.

How is a mention different from a comment or a DM?

A comment is a public reply on a post you own, and you can reply, hide, or delete it. A DM is a private thread governed by platform messaging rules. A mention is a reference to your brand on a surface you do not own, so you can read it and sometimes reply, but you cannot moderate it and it may change or disappear. That ownership difference is why mentions are treated as a real-time discovery stream rather than a durable stored record.

Do all platforms expose mentions through their API?

No, and any documentation implying otherwise is overselling. Some platforms expose a first-class mentions or tags surface, some only return mentions through a search-style query with a different latency and reliability profile, and some do not offer programmatic access to arbitrary third-party mentions at all. Treat coverage as something to confirm in the current product reference before scoping a feature, because the matrix changes when platforms version their APIs.

Should I poll for mentions or use webhooks?

Use both, for different jobs. Poll for backfill on first connect, for platforms that only expose mentions through search, and as a reconciliation pass after an outage. Use push for real-time inbound, because an unanswered negative mention is the failure case for brand monitoring and polling imposes a latency floor. The push delivery mechanism itself, including signature verification and retries, is covered in the social listening webhooks guide; the choice in a mentions context is the design decision above it.

How do I deduplicate brand mentions?

Key everything on the interaction id. In SocialAPI.ai a mention id carries the prefix sapi_mnt_, and that prefix encodes the type so you can dispatch without a database lookup. A reconciliation poll can re-surface a mention you already received via push, and a delivery retry can replay the same event. So a claim-once check on the id (return early if you have seen it) is what keeps your sentiment scoring and alerting from firing twice on the same mention.

Are mentions stored by the API?

Mention content is proxied real-time and not stored as durable content by the API, because a mention lives on a surface you do not own and can be edited or deleted by its author at any time. Your brand monitor stores what it needs to operate: the interaction id, the platform, the sentiment score, and a timestamp, enough to trend over time and to avoid reprocessing. It does not need to mirror someone else's post to do its job.

Social Media Mentions API: Brand Monitoring Across Platforms

A social media mentions API reads every place your brand is named or tagged across the platforms you have connected. It returns each one in a single normalized shape, so your code can process them without per-platform branching. It is the read side of brand monitoring. Someone @-mentions your handle, tags you in a post, or names you in a comment somewhere you do not own. The API surfaces that as one interaction with a stable id, a platform, an author, and content. A brand monitoring API is the same idea framed by the job it serves: track what is said about you, route it, score it, and respond before it becomes a problem. This post covers what a mentions API is, how cross-platform coverage really works, the polling versus push decision, and the architecture of a brand monitor that deduplicates, scores sentiment, alerts, and stores.

A social media mentions API is an interface that collects the places your brand is referenced across social platforms and exposes them through one consistent contract. A mention is any reference to you that happens on a surface you do not control: an @-mention of your handle, a tag in someone else's post, your name in a comment under an account that is not yours. That is the structural difference from comments and DMs, and it shapes everything downstream.

Brand monitoring is the job; the mentions API is the mechanism. The reason teams want this as an API rather than a dashboard is that the interesting work is automated: route a negative mention to support, score sentiment for a weekly trend, alert a channel when volume spikes, attribute a mention to a campaign. A dashboard ends at a human reading a feed. An API lets your own system act on each mention the moment it is known.

The conceptual model here is the same Interaction object used across the rest of the inbox. A mention is one type of interaction alongside comments, DMs, and reviews, and the deeper rationale for normalizing all four into one shape is covered in the unified social inbox API pillar. This post stays on mentions specifically: their coverage, their delivery trade-off, and the monitor you build on top of them.

Mentions vs comments vs DMs: the entity distinction

Mentions, comments, and DMs are three different entities, and conflating them is the most common modeling mistake in a brand monitor. The distinction is not cosmetic. It changes who initiates the interaction, what scope it lives in, whether you own the surface, and therefore how you store and respond to it. The table below is the qualitative version; there are no volume numbers here because volume depends entirely on the account.

	Mention	Comment	Direct message
What it is	A reference to your brand somewhere you do not own	A public reply on a post you own	A private one-to-one or thread conversation
Scope	Anywhere on a platform: posts, comments, captions	Bound to a specific post you control	Bound to a conversation thread
Who initiates	A third party, unprompted by you	A user reacting to your content	A user (or you) opening a private thread
Surface ownership	Not yours: you can read, sometimes reply	Yours: you can reply, hide, delete	Shared: governed by platform messaging rules
Storage stance	Proxied real-time, treated as discovery	Stored where the post is stored	Proxied real-time, never stored as content

Read the surface-ownership row twice. Because a mention lives on a surface you do not control, you cannot rely on it being there later, you cannot moderate it, and your reply (if the platform even allows one) lands in someone else's thread. That is why a mentions API treats mentions as a discovery stream to be acted on quickly, not a durable record to be managed like a comment.

The reply mechanics also diverge. A comment reply and a DM send have their own constraints; for the private side specifically, the messaging window and thread behavior are their own topic. Reviews are a fourth entity again, read-and-respond on a business profile, covered in the online reviews API guide. The point of a mentions API is that all four share one envelope while keeping these behavioral differences explicit rather than hidden.

Which platforms expose mentions, and which do not?

Mention coverage is uneven across platforms, and any honest mentions API documentation says so rather than implying every platform behaves the same. The structural reason: some platforms treat a mention as a first-class event they will tell you about, while others only let you discover mentions through a search-style query, and a few do not expose third-party mentions through their API at all. The right mental model is a spectrum, not a checkbox.

At one end, a platform may expose a mentions or tags surface where being @-mentioned or tagged is something the API reports for accounts you have authorized. In the middle, a platform may only return mentions via a search or query endpoint, which is a different reliability and latency profile. At the other end, some platforms simply do not offer programmatic access to arbitrary third-party mentions, and no abstraction can manufacture data a platform refuses to expose.

This matrix changes when platforms version their APIs. So the safe engineering posture is to treat coverage as something you confirm before you scope a feature, not something you assume from a marketing page. A given platform may expose a mentions or tags surface today; confirm the current behavior in the reference rather than hardcoding an assumption. You can see the full list of supported platforms and check which ones currently expose mentions. The precise endpoint behavior lives in the SocialAPI.ai documentation, so it stays current instead of drifting in a blog post.

The value of a unified mentions API on uneven ground is failure shape. When a platform does not support mention discovery, a well-designed API returns one stable not-supported error rather than letting each native API fail in its own way: an empty array here, a permissions error there, a silent omission somewhere else. Your fallback logic stays singular even when coverage is not.

Polling vs push: which to use for mention monitoring?

For mention monitoring, the polling versus push question is a design decision, not a setup procedure, and the decision is usually both rather than either. Pull (REST polling) is right when you are reconstructing state: an initial backfill of recent mentions on first connect, a periodic sweep for platforms that only expose mentions through search, and a reconciliation pass to catch anything a downstream outage missed. Push is right for the part that has to be fast.

Weigh the two against each other and the trade-off has a clear shape. Polling gives you a detection-latency floor set by your interval and spends quota whether or not a mention happened, which is wasteful because most accounts are quiet most of the time. Push removes that floor and only does work when a mention actually fires, at the cost of running an always-on endpoint. For brand monitoring, where a negative mention left unanswered for an hour is the failure case, push is the default for inbound and pull is the safety net.

How the push side actually works (registering an endpoint, verifying the payload signature, handling retries and backoff) is a separate concern with its own depth, and re-teaching it here would only duplicate it. SocialAPI.ai delivers a mention as a mention.received event the moment it is known; the full delivery mechanism, including signature verification and the retry schedule, is the canonical subject of the social listening webhooks guide. Read that for the mechanism. The decision you are making in this post is upstream of it: pull for backfill and reconciliation, push for real-time inbound, and design your monitor so it does not care which path a mention arrived on.

Building a brand monitor: dedupe, sentiment, alerting, storage

A brand monitor is four steps after the mention arrives: normalize, deduplicate, score sentiment, then alert and store. Normalization is what the mentions API gives you for free, so your code starts at deduplication. The pipeline below is the whole architecture, and the property that makes it tractable is that every mention, from every platform, through pull or push, has the same shape and the same stable id.

Brand mention monitor pipeline

Mention sources normalize into one Interaction (sapi_mnt_), dedupe on the interaction id, score sentiment, then fan out to alert, store, and dashboard. The same pipeline serves pull and push input.

Deduplication comes first because mentions arrive more than once. A reconciliation poll can re-surface a mention you already saw via push, and a delivery retry can replay the same event. In practice the reconciliation poll, not the retries, is the source of most duplicate mentions we see, because the poll window deliberately overlaps what push already delivered. The fix is to key everything on the interaction id. In SocialAPI.ai a mention id has the prefix sapi_mnt_, and the prefix encodes the type so you can dispatch without a database lookup. Treat that id as the primary key: if you have processed it, stop.

javascript

// Normalize + dedupe handler for an incoming brand mention.
// Works the same whether the mention arrived via a poll or a push,
// because the Interaction shape and the id are identical either way.

async function ingestMention(interaction) {
  // 1. Guard: this pipeline is for mentions only.
  //    The id prefix encodes the type, no lookup needed.
  if (!interaction.id.startsWith("sapi_mnt_")) return;

  // 2. Dedupe on the stable interaction id.
  //    Retries and reconciliation polls replay the same id;
  //    SETNX-style claim returns false if we have seen it.
  const fresh = await store.claim(interaction.id);
  if (!fresh) return; // already processed, stop here

  // 3. Normalize into the row your monitor reasons about.
  //    No switch on platform: the envelope is the same for all.
  const mention = {
    id: interaction.id,
    platform: interaction.platform,        // instagram | threads | ...
    author: interaction.author?.id ?? null,
    text: interaction.content?.text ?? "",
    seenAt: new Date().toISOString(),
  };

  // 4. Score sentiment, then fan out. Keep this off the
  //    request path; enqueue and let a worker do the heavy work.
  mention.sentiment = await classify(mention.text); // pos | neu | neg
  await Promise.all([
    mention.sentiment === "neg" ? alert(mention) : null,
    persist(mention),
  ]);
}

Sentiment scoring is the third step, and the only rule that matters architecturally is to keep it off the hot path. Whether you call a hosted model or a local classifier, it is slower than a dedupe check, so enqueue the mention and let a worker score it. Negative is the class your alerting cares about most, because an unhappy mention you answer in minutes is recoverable and one you find next week is not.

Alerting and storage are the fan-out. Alerting is conditional: route negative mentions, or volume spikes, to wherever a human will see them fast. Storage is your own decision and worth being deliberate about. The mention content itself is proxied real-time and not stored as durable content by the API, because it lives on a surface you do not own and can change or vanish. Your monitor stores what it needs: the id, the platform, the score, a timestamp, enough to trend and to avoid reprocessing, not a mirror of someone else's post you are not entitled to keep.

Why route mentions through one API?

Every platform that exposes mentions does it differently: a different surface name, a different auth scope, a different payload, a different idea of what counts as a mention, a different policy for whether you can reply. Wiring each one independently means you build and then permanently maintain a separate mention path per platform, and each one breaks on its own schedule when that platform versions.

Routing mentions through one API collapses that into a single contract. One interaction shape, one stable id scheme, one not-supported error for the platforms that do not expose mentions, one parser for both pull and push input. The handler you saw above does not change when you add a platform or when a platform changes its native API underneath, because the normalization happens below your code. That is the entire reason a brand monitoring API exists as a layer rather than a folder of per-platform clients.

The honest framing is ownership, not magic. A unified mentions API does not make a platform expose data it withholds, and it does not make polling faster than it is. What it does is move the per-platform integration tax, and the breakage when a platform changes, off your team and behind one interface, so a mention from anywhere is just another row your monitor already knows how to process.

Frequently asked questions

What is a social media mentions API?: A social media mentions API reads the places your brand is named or tagged across the platforms you have connected and returns each one in a single normalized interaction object. A mention is a reference to you on a surface you do not own, which makes it a discovery stream rather than an inbox you control. The same handler can process a mention from any platform because the shape and the stable id are identical regardless of where the mention originated.
Is a brand monitoring API the same thing as a mentions API?: They describe the same mechanism from two angles. Mentions API names the data: every reference to your brand, normalized. Brand monitoring API names the job that data serves: tracking and responding to what is said about you. In practice you use one API to read mentions and then build the monitor (dedupe, sentiment, alerting, storage) on top of it. The API is the read layer; the monitor is what you do with it.
How is a mention different from a comment or a DM?: A comment is a public reply on a post you own, and you can reply, hide, or delete it. A DM is a private thread governed by platform messaging rules. A mention is a reference to your brand on a surface you do not own, so you can read it and sometimes reply, but you cannot moderate it and it may change or disappear. That ownership difference is why mentions are treated as a real-time discovery stream rather than a durable stored record.
Do all platforms expose mentions through their API?: No, and any documentation implying otherwise is overselling. Some platforms expose a first-class mentions or tags surface, some only return mentions through a search-style query with a different latency and reliability profile, and some do not offer programmatic access to arbitrary third-party mentions at all. Treat coverage as something to confirm in the current product reference before scoping a feature, because the matrix changes when platforms version their APIs.
Should I poll for mentions or use webhooks?: Use both, for different jobs. Poll for backfill on first connect, for platforms that only expose mentions through search, and as a reconciliation pass after an outage. Use push for real-time inbound, because an unanswered negative mention is the failure case for brand monitoring and polling imposes a latency floor. The push delivery mechanism itself, including signature verification and retries, is covered in the social listening webhooks guide; the choice in a mentions context is the design decision above it.
How do I deduplicate brand mentions?: Key everything on the interaction id. In SocialAPI.ai a mention id carries the prefix sapi_mnt_, and that prefix encodes the type so you can dispatch without a database lookup. A reconciliation poll can re-surface a mention you already received via push, and a delivery retry can replay the same event. So a claim-once check on the id (return early if you have seen it) is what keeps your sentiment scoring and alerting from firing twice on the same mention.
Are mentions stored by the API?: Mention content is proxied real-time and not stored as durable content by the API, because a mention lives on a surface you do not own and can be edited or deleted by its author at any time. Your brand monitor stores what it needs to operate: the interaction id, the platform, the sentiment score, and a timestamp, enough to trend over time and to avoid reprocessing. It does not need to mirror someone else's post to do its job.

A social media mentions API is not a feed widget; it is the read layer a brand monitor is built on. The model that makes it work is the same one the rest of this cluster shares: one normalized interaction, a delivery decision between pull and push, and an honest acceptance that platform coverage is uneven. Start from the entity distinction so you store mentions correctly. Dedupe on the interaction id so retries do not double-fire. Read the social listening webhooks guide when you are ready to wire the real-time path. The conceptual map for all four inbox surfaces is the unified social inbox API pillar.