# Listening (/docs/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. ```bash title="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"}}' ``` ```json title="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`](/docs/idempotency.md), so a retry never creates a second listener. ```bash title="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"}}' ``` ```json title="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 - [Listening overview](/docs/listening/overview.md): Boolean topics, account lists, comments and every option. - [Listening quickstart](/docs/listening/quickstart.md): Walk through the whole dry-run answer and the create call. - [Listening pricing](/docs/listening/pricing.md): Set the monthly cap from a budget. - [Events feed](/docs/events.md): Read mentions from a cursor, or get them pushed to a webhook.