# Monitors (/docs/engines/monitors) Repeat one API call on a schedule, keep only the numbers you choose and get told when they change, priced free before you create it A Monitor repeats one request on a schedule and keeps what changed. This page watches the follower count of a public TikTok profile once a day. Price it first, because the dry run costs nothing and creates nothing. ## Price it for free Add `dry_run=1` to the create call. `recipe` is the API call the Monitor repeats, here `tiktok/profile`. `track` names the number to keep, here the profile's followers. ```bash title="cURL" curl -X POST "https://www.socialcrawl.dev/v1/monitors?dry_run=1" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Charli followers", "recipe": "tiktok/profile", "params": { "handle": "charlidamelio" }, "cadence": "daily", "track": { "metrics": ["author.followers"] } }' ``` ```json title="Response (trimmed)" { "success": true, "platform": "monitors", "endpoint": "/v1/monitors", "data": { "valid": true, "normalized_body": { "recipe": "tiktok/profile", "params": { "handle": "charlidamelio" }, "cadence": "daily", "name": "Charli followers", "track": { "metrics": ["author.followers"] } }, "estimate": { "kind": "monitor_quote", "hold": 0, "recipe_cost_per_run": 1, "scheduling_premium": 1, "estimated_cost_per_run": 2, "runs_per_month": 30, "estimated_monthly_cost": 60, "monthly_cap": null, "first_run_billed_at_creation": false, "next_run_at": "2026-11-19T12:14:13.084Z", "formula": "(1 for tiktok/profile + 1 scheduling premium) x 30 runs a month = 60 credits a month.", "warnings": [] } }, "credits_used": 0 } ``` The dry run checks the request exactly as the real call does. A misspelled number such as `author.follwers` comes back as a `400` that says `Did you mean 'author.followers'?`, so a Monitor that exists records a real number. It checks your Monitor limit too: an account already at its limit gets `403 MONITOR_LIMIT_REACHED`, which names the pack that raises it (the limits are at the foot of this page). ## What does it cost? Each run costs the price of the call it repeats plus 1 credit. A profile read is 1 credit, so a daily Monitor is 2 credits a day, 60 in a month. Creating it holds and charges nothing. The first run happens at `next_run_at`. A run that fails, or finds none of your numbers, is refunded. To stop a Monitor spending more than you plan, add `max_credits_per_month`. The run that would pass it is skipped, not charged, and the Monitor pauses until the 1st of the next month (UTC). ## Create it Send the same body without `dry_run`. ```bash title="cURL" curl -X POST "https://www.socialcrawl.dev/v1/monitors" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Charli followers", "recipe": "tiktok/profile", "params": { "handle": "charlidamelio" }, "cadence": "daily", "track": { "metrics": ["author.followers"] } }' ``` ```json title="Response (trimmed)" { "monitor": { "id": "mon_7Qk2R9xLpV", "name": "Charli followers", "recipe": "tiktok/profile", "cadence": "daily", "status": "active", "estimated_cost_per_run": 2, "estimated_monthly_cost": 60, "track": { "metrics": ["author.followers"], "row_key": null, "max_rows": 100 }, "warnings": [] }, "webhook_secret": null } ``` This call is not safe to repeat blindly. After a timeout, list your Monitors with `GET /v1/monitors` before you send it again. ## How do results reach you? You have three options, and you can combine them. - **Download.** With no `webhook_url`, the Monitor is download-only. Read `GET /v1/monitors/{monitor_id}/timeseries` for every stored reading, or `GET /v1/monitors/{monitor_id}/export?format=csv` for a spreadsheet with the change since each run. Both are free. - **Push.** Add a `webhook_url` and each completed run is posted there, signed. Add `webhook_rows: "new"` to a list Monitor and it sends only rows it has not seen before. - **Alerts.** Add `alert_rules`, for example `{ "metric": "author.followers", "op": "pct_change_gt", "value": 5 }`, and set `suppress_webhook_unless_alert` so your endpoint hears from you only when a rule fires. Verifying signatures, retries and the exact payloads are on the pages below. You can pause a Monitor with `PATCH /v1/monitors/{monitor_id}` and `{"status": "paused"}`. The history is kept. An account keeps a limited number of active Monitors, set by the largest credit pack it has bought: Free 3, Starter 10, Growth 25, Pro 100 and Enterprise 500. ## Next steps - [Watch something over time](/docs/webhooks-and-events.md): Which watch fits your job, and how its results reach you. - [Monitor webhooks](/docs/webhooks.md): Every field, the payloads, alerts, export and signature checks. - [Track sound growth](/docs/recipes/track-sound-growth.md): A worked recipe: a daily count, a time series and an alert. - [Listening](/docs/engines/listening.md): Watch a topic or a keyword instead of one profile.