SocialCrawl
Engines

Listening

Watch keywords, a topic or named accounts and get each new mention once, with the monthly price shown free before you create it

A listener watches keywords, a topic or a list of accounts on Reddit, YouTube, X, Naver, Google News, TikTok, Facebook, Threads and LinkedIn. It checks on a schedule and delivers each new post once, as a mention. Price one first. The dry run costs 0 credits and creates nothing.

Price it for free

Send the body you would create with, and add dry_run=1. This listener watches ChatGPT on Reddit and YouTube every hour.

cURL
curl -X POST "https://www.socialcrawl.dev/v1/listening/streams?dry_run=1" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["ChatGPT"], "platforms": ["reddit", "youtube"], "schedule": {"every": "1h", "name": "ChatGPT chatter"}}'
Response (trimmed)
{
  "success": true,
  "data": {
    "dry_run": true,
    "stream": {
      "groups": [
        { "keywords": ["ChatGPT"], "read_back": "Posts mentioning “ChatGPT”" }
      ],
      "platforms": ["reddit", "youtube"],
      "schedule": { "every": "1h", "name": "ChatGPT chatter" }
    },
    "estimate": {
      "month": "2026-11",
      "slots_in_month": 720,
      "searches_per_slot": 2,
      "credits_per_month": 1440,
      "depth_range_credits_per_month": [1440, 4320],
      "max_credits_per_slot": 6,
      "recommended_max_credits_per_month": 4911,
      "expected_net_credits_per_month": 1435
    },
    "screen": { "result": "allowed" }
  },
  "credits_used": 0
}

Read four things. read_back says in words what the listener will match. credits_per_month is a typical month when each search reads one page. depth_range_credits_per_month runs up to three pages a search. recommended_max_credits_per_month is the monthly cap to send next. screen.result says whether the use screen accepts the topic. The answer also quotes the most a month can bill in money.

Create it

Send the same body with a monthly cap, schedule.max_credits_per_month. The cap is required. Add an Idempotency-Key, so a retry never creates a second listener.

cURL
curl -X POST "https://www.socialcrawl.dev/v1/listening/streams" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"keywords": ["ChatGPT"], "platforms": ["reddit", "youtube"], "schedule": {"every": "1h", "max_credits_per_month": 5000, "name": "ChatGPT chatter"}}'
Response (trimmed)
{
  "success": true,
  "data": {
    "stream": { "id": "lst_7AxziQ8a0R2Wg7970F39H" }
  }
}

The first check runs at once. It records the posts already out there as a baseline and sends them nowhere, so you are not flooded with old posts. Every check after that delivers only posts it has not seen.

What does it cost?

A listener pays for the searches each check makes, and never more than its monthly cap. A check can run as often as every 30 minutes. A page that finds nothing new is refunded on sources that list the newest posts first. Reading mentions costs 0 credits.

How do mentions reach you?

  • Read them. GET /v1/listening/streams/{listener_id}/mentions returns each mention in one shape whichever platform it came from. It is free.
  • Pull the feed. GET /v1/events with types=mention.* returns what is new since your last read.
  • Get them pushed. Register a webhook endpoint once and each new mention arrives as a signed mention.created event.

Next steps

On this page