Monitors API
A monitor watches a source on a schedule and hands you only what is new: a hashtag's new videos, new posts matching a keyword, an account's new posts, new reviews of an app. Each item reaches you once. Nothing runs on your side.
Authentication
Use the same API key as every other call, as Authorization: Bearer <key> or x-api-key: <key>. A key limited to some platforms can only set up monitors on those platforms. Monitors are on https://api.fetchlayer.dev/monitors. Each key may make 120 monitor requests a minute.
curl https://api.fetchlayer.dev/monitors \
-H "Authorization: Bearer ss-your-key"Create a monitor
POST /monitors. Fields:
sources: what to watch, one or more{ capabilityId, params }, for exampletiktok:hashtag-videoswith{ "hashtag": "yourbrand" }. One monitor can watch several platforms, and their new items arrive together.tiktok:hashtag-videosalso takespages(1–7, how far down the hashtag each check reads, 30 posts a page; TikTok lists its top 170 to 200 or so, popular first, so 7 reads them all) andrequireHashtag(true: only posts whose own caption carries the tag). Changing either keeps the monitor's history.schedule.intervalMinutes: one of 5, 15, 60, 360, 1440. OptionalquietHoursStart/quietHoursEnd(0–23) andtimezone.delivery: where new items go:webhook(your https URL gets JSON),email,slackordiscord. Defaults to your account email.filters:includeKeywords,excludeKeywords, and an optional AI relevance filter (aiEnabledwithaiCriteriain plain English).maxAlertsPerDay: a safety cap, up to 10,000 for a monitor made with a key.nameis optional.
curl -X POST https://api.fetchlayer.dev/monitors \
-H "Authorization: Bearer ss-your-key" \
-H "Content-Type: application/json" \
-d '{
"name": "#yourbrand on TikTok",
"sources": [{ "capabilityId": "tiktok:hashtag-videos", "params": { "hashtag": "yourbrand" } }],
"schedule": { "intervalMinutes": 60 },
"delivery": [{ "type": "webhook", "target": "https://example.com/hooks/fetchlayer" }],
"maxAlertsPerDay": 5000
}'The answer is 201 with the monitor. Its first check takes a silent first look: everything already there is recorded as seen, so you are only told about what appears after it. A monitor made with a key runs its first check within its first interval (at most an hour), at a time spread across that interval, so that many monitors created together don't all run at the same moment. nextRunAt says when.
Each item once, for good
List, read, update, delete
GET /monitors: every monitor on the account, newest first.GET /monitors/:id: one monitor, its latest results and its recent checks.PATCH /monitors/:id: send the full monitor (the same fields as create) to change it. Delivery targets come back masked, because a webhook URL is a credential. Send{ "type": "webhook", "keep": true }to keep the stored one.PATCH /monitors/:idwith only{ "paused": true }or{ "paused": false }: pause or resume. Resuming runs a check straight away.DELETE /monitors/:id: removes the monitor, its results and its delivery log.
Read results with a cursor
GET /monitors/:id/hits pages through what the monitor kept. For a daily job, ask oldest first from your last pull, and follow nextCursor until it is null:
order:asc(oldest first) ordesc(newest first, the default).since: ISO 8601; only results recorded at or after it.limit: 1–100, default 25.cursor: the previous page'snextCursor, unchanged, with the sameorder. Paging is exact: nothing is skipped or repeated, even while new results arrive.view=filtered: what the filters left out, instead of what was kept.platform: one platform's results.
curl "https://api.fetchlayer.dev/monitors/<id>/hits?order=asc&since=2026-11-10T00:00:00Z&limit=100" \
-H "Authorization: Bearer ss-your-key"{
"hits": [
{
"id": "…",
"capabilityId": "tiktok:hashtag-videos",
"verdict": "matched",
"delivery": "sent",
"createdAt": "2026-11-10T14:02:11.204Z"
}
],
"hasMore": true,
"nextCursor": "eyJ0Ijoi…"
}What a webhook receives
One JSON POST per check that found something, with every new item from every platform the monitor watches. Each item has a stable id, its platform, the summary fields, and in raw the platform's full record for it: for a TikTok video, the same video object the TikTok endpoints return.
{
"event": "monitor.items",
"deliveryId": "2f0c…",
"monitor": {
"id": "…",
"name": "#yourbrand on TikTok",
"url": "https://fetchlayer.dev/dashboard/monitors/…"
},
"capability": "tiktok:hashtag-videos",
"count": 1,
"digest": "new",
"deferredCount": 0,
"contentAvailable": true,
"items": [
{
"id": "673a…",
"capabilityId": "tiktok:hashtag-videos",
"body": "caption…",
"author": "someone",
"url": "https://www.tiktok.com/@someone/video/…",
"score": 1520,
"publishedAt": "2026-11-10T13:58:00.000Z",
"matchReason": null,
"raw": {
"id": "…",
"description": "caption…",
"stats": {
"playCount": 1520
}
}
}
]
}Headers on every POST:
X-FetchLayer-Delivery: the same on every attempt of one POST (alsodeliveryIdin the body). If you already handled it, answer 2xx and drop it. Each item'sidis stable too, so a repeated item is safe to ignore.X-FetchLayer-Attempt: 1 to 5.X-FetchLayer-Event:monitor.items.X-FetchLayer-Signature:t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of<t>.<raw body>keyed with the monitor's webhook secret.
import crypto from 'node:crypto';
function verify(secret, header, rawBody) {
const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // too old: a replay
const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));
}The secret (whsec_…) is returned once, as webhookSecret, when you create a monitor with a webhook or add one to it. Send PATCH /monitors/:id with { "rotateWebhookSecret": true } to get a new one; the old one stops verifying at once.
Retries
GET /monitors/:id/deliveries is the delivery log, kept for 30 days. Each row is one POST: its id, how many items it carried, its state (delivered, retrying, failed), and every attempt's status and time. Filter with ?status=, ?limit= and ?before=. The same log is on the monitor's page in the dashboard.
digest: "backlog" marks the one message a new monitor may send about what was already there when it started.
Where results are readable
A monitor's deliveries is either server-readable or sealed. With server-readable, each result's item and raw record are kept, encrypted, for 7 days. That lets a retried webhook carry the items, and lets GET /monitors/:id/hits return them (the summary fields plus raw). With sealed, results can be read only on your own signed-in devices. An alert sent after the moment of finding then gives the count (deferredCount, contentAvailable: false) instead of the items. A new monitor is sealed unless you say otherwise or your account has another default; every monitor's deliveries field says which it is. A server-readable copy is deleted 7 days after the result was found, whether or not it was delivered. Set it when you create the monitor, or change it on its own with PATCH /monitors/:id and { "deliveries": "sealed" }. Switching back to sealed deletes the readable copies at once.
Errors and billing
401: a missing or invalid key. 403: a key scoped to other platforms, a trial key, an account at its monitor limit, or a route that is only in the dashboard. 404: a monitor that is not yours. 400: names the field that is wrong. 429: slow down. Each check is billed like the same API call made with your key, for every platform it reads; a check that cannot reach a platform costs nothing.
{
"error": "Pick one of the offered check frequencies."
}