Concepts

Mention monitors

A monitor watches one term, such as your brand, a product, a domain or a competitor, across seven platforms, and keeps every new mention in a feed. Give it a webhook and we call you as each one is found.

No code needed: Mentions in the dashboard creates and reads the same monitors as the routes below, with an unread inbox on top. For what it costs and how it compares to other mention tools, see mention monitoring.

What does a monitor check?

On every check, each platform is searched for the term. A result counts as a mention only when the term appears as a whole word in its title or text, ignoring case: acme matches “Acme’s” but not “acmes”. Instagram and TikTok have no logged-out search, so there a monitor reads the term’s hashtag (truescrape.com becomes #truescrape) and every post there counts. That is the posts the platform shows for the tag, not every post that uses it.

newest posts matching the term

Hacker News

stories and comments matching the term

Bluesky

Create a monitor

Only term is required. platforms defaults to all seven, interval_seconds to 21600 (every 6 hours), and webhook_url is optional: without one, mentions still collect in the feed.

request

curl -X POST "$API/v1/monitors" \
  -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{
    "term": "acme",
    "platforms": ["reddit", "hackernews", "bluesky", "youtube", "threads", "instagram", "tiktok"],
    "interval_seconds": 21600,
    "webhook_url": "https://you.example/hooks/mentions"
  }'

201 Created

{
  "success": true,
  "data": {
    "monitorId": "mon_01JC2F7K3PZ8QD",
    "term": "acme",
    "platforms": [
      { "platform": "reddit", "subscriptionId": "sub_01JC2F7K4A1B2C" },
      { "platform": "hackernews", "subscriptionId": "sub_01JC2F7K4D3E4F" },
      "..."
    ],
    "skipped": [],
    "creditsPerCheck": 7
  }
}

A platform the term cannot be used on is left out and listed in skipped with the reason, for example a term with no letters or digits left to make a hashtag from. creditsPerCheck is the most one check can cost: one credit per platform.

List monitors

One row per monitor. sources gives each platform’s state: active, paused_unpaid (out of credits, resumes on its own after a top-up) or retired (stopped after repeated failed checks). Over the last 7 days, checked is how many results the platform returned and matched how many mentioned the term, so a platform that keeps answering with nothing relevant can be left out of the next monitor.

GET /v1/monitors

{
  "success": true,
  "data": [
    {
      "monitorId": "mon_01JC2F7K3PZ8QD",
      "term": "acme",
      "intervalSeconds": 21600,
      "hasWebhook": true,
      "createdAt": "2026-11-01T09:12:44.000Z",
      "lastCheckedAt": "2026-11-03T15:12:51.000Z",
      "mentionsLast7Days": 23,
      "mentionsTotal": 41,
      "sources": [
        { "platform": "reddit", "subscriptionId": "sub_01JC2F7K4A1B2C", "state": "active",
          "lastCheckedAt": "2026-11-03T15:12:51.000Z", "checked": 700, "matched": 14 },
        "..."
      ]
    }
  ]
}

Read the mentions

Newest first. Without monitor the feed spans every monitor on your team. Pass nextCursor back as cursor for the next page; it is null on the last one.

baseline is true on a mention the first check found: it was already out there when you started watching. Baseline mentions come after the new ones, are never unread, never count toward the summary and are never sent to your webhook.

GET /v1/monitors/mentions?monitor=mon_01JC2F7K3PZ8QD

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "1gx4k2p",
        "url": "https://www.reddit.com/r/analytics/comments/1gx4k2p/",
        "title": "Moving our product analytics to Acme",
        "text": "We switched last month and ...",
        "authorHandle": "dataperson",
        "publishedAt": "2026-11-03T13:40:02.000Z",
        "platform": "reddit",
        "monitorId": "mon_01JC2F7K3PZ8QD",
        "term": "acme",
        "firstSeenAt": "2026-11-03T15:12:51.000Z",
        "baseline": false
      }
    ],
    "nextCursor": "eyJ0IjoiMjAyNi0xMS0wM1QxNToxMjo1MSJ9"
  }
}

The summary is the same four numbers the dashboard shows. daily is the last seven days, oldest first. creditsUsedThisWeek is what the monitor’s checks were actually charged over those seven days. Without monitor it covers all of them.

GET /v1/monitors/summary

{
  "success": true,
  "data": {
    "newToday": 4,
    "thisWeek": 23,
    "daily": [2, 5, 3, 0, 6, 3, 4],
    "topSource": { "platform": "reddit", "count": 14 },
    "creditsUsedThisWeek": 168
  }
}

Delete a monitor

DELETE /v1/monitors/{monitorId} stops checking the term immediately and permanently deletes all of the mentions it found so far, along with its read state and its check history. This can’t be undone.

Webhooks

When a check finds mentions it has never seen before, your webhook receives monitor.new_mentions carrying exactly those, one delivery per platform. A check that finds nothing new sends nothing. Deliveries are signed and retried like every other webhook here; see how to verify a delivery.

monitor.new_mentions

{
  "type": "monitor.new_mentions",
  "monitorId": "mon_01JC2F7K3PZ8QD",
  "subscriptionId": "sub_01JC2F7K4A1B2C",
  "platform": "reddit",
  "term": "acme",
  "items": [
    {
      "id": "1gx4k2p",
      "url": "https://www.reddit.com/r/analytics/comments/1gx4k2p/",
      "title": "Moving our product analytics to Acme",
      "text": "We switched last month and ...",
      "authorHandle": "dataperson",
      "publishedAt": "2026-11-03T13:40:02.000Z",
      "platform": "reddit"
    }
  ]
}

If your balance runs out, the monitor pauses and you receive monitor.paused once for the whole monitor, not once per platform. Top up and it resumes on its own at its next scheduled check.

monitor.paused

{
  "type": "monitor.paused",
  "monitorId": "mon_01JC2F7K3PZ8QD",
  "reason": "unpaid"
}

What does a monitor cost?

1 credit per platform per check, charged whenever the platform answers, even if nothing mentions you; a failed platform costs nothing. There is no charge per mention, so a check that finds fifty costs the same as one that finds none. Creating, listing, reading and deleting monitors cost nothing.

Seven platforms every 6 hours: 4 checks a day, at most 28 credits a day, about 840 a month.
Seven platforms daily (interval_seconds: 86400): at most 7 credits a day, about 210 a month.

Limits

The shortest interval is 1 hour.
Monitors share your team’s limit on checks per hour with your other watches, and every platform counts: seven platforms every 6 hours is about 1.2 checks an hour. A monitor that would go over the limit is refused whole, never half-created.
A team with Zero retention on must give a webhook_url: we keep no mention text for it, so its feed answers 409 and the webhook is the only way to receive them.

What to expect

A new monitor stays quiet at first. Its first check that returns data records what is already out there, and only mentions after that are announced. On YouTube and Instagram it stays quiet for the first 24 hours after that check too, because their results reshuffle.
YouTube and Threads search results are not sorted by date, so a new post may not reach the first page we read. Coverage there is best-effort, and an older YouTube video can occasionally appear as new.
Mentions published more than 7 days before a check are not announced.
A common word as a term (“Linear”, “Notion”) matches far more than your brand. A more specific term, or your domain, keeps the feed useful.

Open Mentions in the dashboard Watches and webhooks

Contents

Site