SocialCrawl
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.

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"] }
  }'
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.

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"] }
  }'
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

On this page