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 -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"}}'{
"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 -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"}}'{
"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}/mentionsreturns each mention in one shape whichever platform it came from. It is free. - Pull the feed.
GET /v1/eventswithtypes=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.createdevent.
