Create a monitor API
Watch a list endpoint (a profile's posts, a search) and receive new items at a webhook.
POST /v1/monitors
POST /v1/monitors
Watch a list endpoint (a profile's posts, a search) and receive new items at a webhook.
- Cost: Free
- Cache: Not cached.
Parameters#
| Name | Type | Required | Description | In |
|---|---|---|---|---|
endpoint | string | yes | Path of a list endpoint, "/v1/tiktok/profile/videos". | body |
params | object | yes | That endpoint's params. | body |
interval_minutes | integer | no | How often to check. Default 60. Range 15 to 1440. | body |
webhook_url | string | yes | HTTPS URL that receives events. | body |
Example request#
Set your key in the environment first (see Authentication).
1curl -X POST "https://api.socialscrape.dev/v1/monitors" \2 -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3 -H "content-type: application/json" \4 -d '{"endpoint":"/v1/github/user/repositories","params":{"handle":"torvalds"},"interval_minutes":60,"webhook_url":"https://example.com/hook"}'1import os2import requests34payload = {5 "endpoint": "/v1/github/user/repositories",6 "params": {7 "handle": "torvalds",8 },9 "interval_minutes": 60,10 "webhook_url": "https://example.com/hook",11}12res = requests.post(13 "https://api.socialscrape.dev/v1/monitors",14 headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},15 json=payload,16)17body = res.json()1819if body["ok"]:20 print(body["data"])21else:22 print(body["error"]["code"], body["error"]["message"])1const res = await fetch("https://api.socialscrape.dev/v1/monitors", {2 method: "POST",3 headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY!, "content-type": "application/json" },4 body: JSON.stringify({"endpoint": "/v1/github/user/repositories", "params": {"handle": "torvalds"}, "interval_minutes": 60, "webhook_url": "https://example.com/hook"}),5});6const body = await res.json();78if (body.ok) {9 console.log(body.data);10} else {11 console.error(body.error.code, body.error.message);12}Example response#
This is a sample with illustrative values. Status 200.
200 OKSample response
1{2 "ok": true,3 "credits_charged": 0,4 "credits_remaining": 5000,5 "cached": false,6 "cached_at": null,7 "request_id": "req_2aebbb49c25ee0daa5da5dd5",8 "data": {9 "object": "monitor",10 "id": "mon_0123456789abcdef",11 "endpoint": "/v1/github/user/repositories",12 "params": {13 "handle": "torvalds"14 },15 "interval_minutes": 60,16 "webhook_url": "https://example.com/hook",17 "active": true,18 "created_at": "2026-10-29T14:00:00Z",19 "webhook_secret": "whsec_sample_secret_shown_once",20 "last_run_at": null,21 "next_run_at": "2026-10-29T14:00:00Z",22 "last_error": null23 },24 "cursor": null,25 "has_more": null26}Response#
A Monitor object in data.
See Data models for every field. The envelope around data is described in Responses.
Errors#
Failures are free: credits_charged is 0. Branch on error.code, never on the message.
| Code | HTTP | Retry | Meaning |
|---|---|---|---|
invalid_params | 400 | no | A parameter is missing, unknown or has the wrong type. |
Every request can also fail with the account and platform errors listed on the Errors page.
Related endpoints#
- List monitors (
GET /v1/monitors) - Delete a monitor (
DELETE /v1/monitors/{monitor_id}) - Send a test event (
POST /v1/monitors/{monitor_id}/test) - Webhook delivery log (
GET /v1/monitors/{monitor_id}/deliveries) - Send an event again (
POST /v1/monitors/events/{event_id}/redeliver) - Monitor events (
GET /v1/monitors/events)